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Preface 



Welcome to the Programmer's 
Introduction 



The Apple JIGS® is a new kind of computer. It offers precise color 
graphics, sophisticated sound hardware, a large memory capacity, 
and an extensive toolbox of programming routines — giving you 
programming resources without precedent among personal 
computers. The Programmer's Introduction to the Affile 1IGS gets 
you started writing programs that take advantage of these unique 
features. 

You needn't be an expert programmer to benefit from this book, 
but we do assume that you know some fundamentals. Your 
background will most likely determine your approach. 

a U you are Familiar with programming other Apple® II 
computers, and wondering how different Apple IlGS 
programming might be,.. 

□ If you are familiar with programming the Macintosh® 

computer, and wondering how similar Apple IlGS programming 
might be... 

D If you are familiar with programming other computers, and 
wondering how rewarding Apple IlGS programming might be... 

o If you are familiar with using the Apple 1IGS, and wondering 
how much fun Apple IlGS programming might be... 

...this book will help get you started. It can't be a complete 
programming course, but it does cover the major features that set 
the Apple IlGS apart and make it an exciting machine to write 
programs for. 
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You should be familiar with the Apple IIGS, at least from a user's 
perspective, before you start this book, In particular, you should 
understand how to start the system and how to use the keyboard, 
mouse, and disk drives. 

We don't teach you any programming languages here. The books 
listed in the next section under "Roadmap to the Apple IIGS 
Technical Manuals" can help you with C and 65816 assembly 
language. The other Apple IIGS technical manuals cover 
individual topics in far greater detail than we can here; please 
consult them as needed. 

<* Toolbox manual: It is not possible to write the kind of program 
described here without the aid of the Apple IIGS Toolbox 
Reference. We give lots of examples and general call 
descriptions in this book, but you'll need both volumes of the 
Toolbox Reference if you want to write your own applications. 



Roadmap to the Apple IIgs technical 
manuals 

The Apple IIGS personal computer has many advanced features, 
making it more complex than earlier models of the Apple IL To 
describe it fully, Apple has produced a suite of technical manuals. 
Depending on the way you intend to use the Apple IIGS, you may 
need to refer to a select few of the manuals, or you may need to 
refer to most of them. 

The technical manuals are listed in Table P-l. Figure P-l is a 
diagram showing the relationships among the different manuals. 
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Introductory manuals 

The introductory manuals are for developers, computer 
enthusiasts, and other Apple IIGS owners who need technical 
information. As introductory manuals, their purpose is to help the 
technical reader understand the features of the Apple IIGS, 
particularly the features that are different from other Apple 
computers. 

■ The technical introduction; The Technical Introduction to the 
Apple IIGS is the first book in the suite of technical manuals 
about the Apple IIGS. It describes all aspects of the Apple IIGS, 
including its features and general design, the program 
environments, the toolbox, and the development environment 

■ The programmer's introduction (this book)t When you start 
writing Apple IIGS programs, the Programmer's Introduction to 
the Apple IIGS provides the concepts and guidelines you need. 
It is not a complete course in programming, only a starting 
point for programmers writing applications that use the Apple 
desktop interface (with windows, menus, and the mouse). It 
introduces the routines in the Apple IIGS Toolbox and includes 
a sample event-driven program. 



Machine reference manuals 

There arc two reference manuals for the machine itself. They 
contain detailed specifications for people who want to know 
exactly what's inside the machine. 

■ The hardware reference manual: The Apple IIGS Hardware 
Reference is required reading for hardware developers and 
anyone else who wants to know how the machine works. 
Information for developers includes the mechanical and 
electrical specifications of all connectors, both internal and 
external. Information of general interest includes descriptions 
of the internal hardware and how it affects the machine's 
features. 
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The firmware reference manual; The Apple IIGS Firmware 
Reference describes programs and subroutines stored in the 
machine's read-only memory (ROM). The Firmware Reference 
includes information about interrupt routines and low- level I/O 
subroutines for the serial ports, the disk port, and for the 
Desktop Bus interface, which controls the keyboard and the 
mouse. The Firmware Reference also describes the Monitor 
program, a low-level programming and debugging aid for 
assembly-language programs. 



The toolbox manuals 

Like the Macintosh, the Apple IIGS has a built-in toolbox of 
software routines. The two volumes of the Apple lies Toolbox 
Reference completely describe the calls and data structures for all 
tool sets, and also tell how to write and install your own tool set. 



The desktop Interface is If you are developing an application that uses the desktop 

described in Chapter 1. interface, or if you want to use the Super Hi-Res graphics display, 

you'll find the toolbox indispensable. 



The Programmer's Workshop manual 

The Apple IIGS Programmer's Workshop (APW) is the 
development environment for the Apple IIGS computer — a set of 
programs that enables developers to create application programs. 
The Apple IIGS Programmer's Workshop Reference describes the 
APW Shell, Editor, Linker, and utility programs; these are the parts 
of the workshop that all developers need, regardless of which 
programming language they use. 

The APW reference manual includes a sample program to show 
how to create an application. It also describes object module 
format, the file format used by all APW compilers to produce files 
loadable by the Apple IIGS System Loader, 



Programming-language manuals 

Apple currendy provides a 65C816 assembler and a C compiler. 
Other compilers can be used with the workshop, provided that 
they follow the standards defined in the Apple IIGS Programmer's 
Workshop Reference. 



tfvii Preface: Introduction to the Programmer's Introduction 



There is a separate reference manual for each programming 
language. Each manual includes the 5 perinea lions of the language 
and of the Apple NGS libraries for the language, and describes 
how to use the assembler or compiler for that language. The 
manuals for the languages Apple provides arc the Apple HGS 
Programmer's Workshop Assembler Reference and Lhe Apple HGS 
Programmer's Workshop C Reference. 

<& Note,- The Apple HGS Programmer's Workshop Reference and 
the two programming-language manuals are available through 
the Apple Programmer's and Developer's Association (APDA). 



Operating -system manuals 

There are two operating systems that run on the Apple 1IGS; 
ProDOS® 16 and ProDOS 8. Each operating system is described 
in its own manual: the Apple HGS ProDOS 16 Reference and the 
ProDOS 8 Technical Reference Manual ProDOS 16 uses the Full 
power of the Apple HGS. The ProDOS \& manual describes its 
features and includes information about the System Loader, which 
works closely with ProDOS \6 to load program segments into 
memory. 

ProDOS 8, previously called ProDOS, is the standard operating 
system for most Apple II computers with 8-bit CPUs. It also runs 
on the Apple HGS, but it cannot access certain advanced Apple 
HGS features. 



All-Apple manuals 

There are two manuals that apply to all Apple computers: Human 
Interface Guidelines: lhe Apple Desktop Interface and Apple 
Numerics Manual If you develop programs for any Apple 
computer, you should know about those manuals. 
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The Human Interface Guidelines manual describes Apple's 
standards for the desktop interface of any program that runs on 
Apple computers. If you are writing a commercial application for 
the Apple IIGS, you should be familiar with the contents of this 
manual. 

The Apple Numerics Manual is the reference for the Standard 
Apple Numeric Environment (SANE™), a full implementation of 
the IEEE Standard for Binary Floating-Point Arithmetic (IEEE Std 
754-1985). If your application requires accurate or robust 
arithmetic, you'll probably want to use the SANE routines in the 
Apple IIGS. 



How to use this book 

The Programmer's Introduction is not a tutorial. Rather than ask 
you to type in line after line of code, we've built the book around 
a finished example — a sample program named HodgePodge. 
HodgePodge is a fully functioning framework of an application 
that demonstrates most of the programming concepts we present 
in this book. More than that, HodgePodge is a rather 
heterogeneous collection of generally useful Apple IIGS 
routines — hence its name. You are invited to study, copy, or 
incorporate any of those routines, wholesale or piecemeal, 
unchanged or greatly altered, into your own programs, 

Stan by reading Chapter 1. It introduces the basic concepts of this 
book— event-driven programming, the desktop user interface, the 
Apple IIC.S Toolbox, and program segmentation. 

Then run HodgePodge to see what it does. At that point you 
should be ready for Chapter 2, an extensively annotated set of 
source listings of the principal parts of HodgePodge. The listings 
give you the big picture on how event-driven programs are 
organized, demonstrate how heavily desktop programming relies 
on toolbox calls, and function as templates for you to use in your 
own programming. Complete source listings in Pascal, C, and 
65816 assembly language, are in Appendixes E through G, 
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Chapters 3 through 8 expand further on the concepts of toolbox 
use, memory management, program segmentation, the 
development environment, and specialized program 
requirements. These chapters include sample source listings where 
appropriate, but they also discuss important Apple IIGS concepts 
not represented in any of the samples. They are overviews 
designed to give you ideas to pursue in your own programming 
when aided by other reference manuals. 

Chapter 9 is a brief wrap-up that summarizes general program 
design ideas and shows where to go for further help. 

Appendixes include hints on converting existing Macintosh 
applications to run on the Apple DCS, and enhancing existing 
Apple 1! applications to take full advantage of the new Apple IIGS 
features, 

♦ Mote: Please don't feel that you need to read this book in any 
order. Skipping around among programming examples, 
explanations, and theory may be the best way to absorb the 
material presented here. Most important of all, experiment cm 
the Apple IIGS as you go along. Use HodgePodge or write your 
own examples. 



Terms and conventions 

This book may define certain terms in a slightly different manner 
from which you are accustomed. Here are two: 

■ Apple II: A general reference to the Apple II family of 
computers. It includes the Apple II, Apple II Plus, Apple He, 
Apple lie, and Apple IIGS. 

■ standard Apple II: Any Apple II computer that is no! an Apple 
IIGS. Because previous members of the Apple II family share 
many characteristics, it is useful to distinguish them as a group 
from the Apple IIGS. A standard Apple II may also be called an 
8-bit Apple //, because of the 8-bit registers in its 6502 or 65C02 
microprocessor. 
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Typographic conventions 

Each new term introduced in this book is printed in bold type 
where ii is first defined. That lets you know thai the term has not 
been defined earlier, and also indicates that there is an entry for 
it in the glossary. 

Assembly-language labels, entry points, program and subroutine 
names, and filenames that appear in text passages are printed in a 
special typeface (for example, DoWItem and MENU . PAS). There 
is one exception: the names or Apple lies system software routines, 
such as toolbox calis and operating system calls (for example, 
NewModalDialog and QUIT), are printed in normal type. 

♦ Note.- The source-code listings of the program HodgePodge 
follow a different, special typographic convention. See "Code- 
Listing Convention" in Chapter 2. 



Watch for these 

The following words mark special messages to you ; 

♦ Note: Text set off in this manner presents sidelights or 
interesting points of information. 

Important Text sot off In this manner- with the word Important-presents 
important information or Instructions. 



Warning Text set off In this manner-wlth the word Warning -Indicates 
potential serious problems, 
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Writing well-designed programs for the Apple IIGS computer is 
both an adventure and a challenge. It may require some changes 
in the way you approach programming, some changes that at First 
seem confusing. But don't worry; there are tools and resources to 
help you at every step, to make the shift in programming style 
relatively easy. And fast. 

As you start, you'll want to keep several key concepts in mind. This 
chapter introduces those basic ideas. We'll be building on them 
throughout the book, and showing examples of them in action, in 
the sample program HodgePodge. They include 

D desktop applications — programs with a user inteface based on 
Apple's Human Interface Guidelines 

D event-driven programming — creating the fundamental internal 
structure of desktop applications 

□ the Apple IfCS Toolbox — the extensive set of programming 
routines that make desktop, event-driven programming 
practical 

D segmentation — -techniques that allow your programs to use 
memory more efficiently 

D development — steps to follow in creating a running program 



A more powerful Apple II 

The Apple IIGS personal computer is a new Apple II with many 
high-performance features. Some of its highlights are 

D a more powerful microprocessor with faster operation than 
processors used in standard Apple II computers, and with a 
24-bit address bus 

□ 256K memory, expandable to 8 megabytes 

□ high-resolution RGB video display for Super Hi-ttes color 
graphics and text 

n multi-voice digital sound synthesizer 

□ detached keyboard with Apple Desktop Bus™ connector 

D built-in I/O: clock, disk port, and serial ports with AppleTalk® 
interface 

n slots and game I/O connectors compatible with standard 
Apple II computers 
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Super Hi-Res video 



Detached keyboard 

Apple Desktop Bus 
Mouse support 






65CS16 processor: 

Expanded memory 

Toolbox ROM routines 

Digital sound synthesizer 



Built-in AppleTalk 
Built-in I/O ports 



7 expansion slots 



*> Note. If you are not familiar with the Apple TJ family of 

computers, you may want to refer to the Technical Introduction 
to the Apple lies or your Apple RGS Owner's Guide for 
explanations of some of the terms in this section. 




A J6-bH processor handles data In 
chunks of 16 bits at a time, twice 
as much data per cycle as an 
8-bit processor . 



Figure 1-1 
Apple IIgs features 



The 65816 microprocessor 

The microprocessor in the Apple IIGS is a 65SC816, a 16-bit 
CMOS design based on the 6502 processor used in previous 
Apple II computers. Among the features of the 65816 are 

□ ability to emulate 6502 and 65C02 3-bit microprocessors 

□ lo-bil accumulator and index registers 



A more powerful Apple 



Stock and direct- page concepts 
are discussed further in Chapter 6. 



a relocatable stack and direct page (zero page) 

□ 24 -bit internal address bus, giving a 16-megabyte memory 
space 



Two execution modes 

The 65816 microprocessor can operate in two different modes; 
native mode, with all of its new features, and 6502 emulation 
mode, for running programs written for standard (8-bil) Apple II 
computers. 

Applications written for the Apple 1IC5 use native mode with the 
accumulator and index registers 16 bits long. Also, the size of the 
stack and the locations of the stack and direct page within bank 
$00 are at the discretion of the application. 

Two clock speeds 

The microprocessor in the Apple IIGS can operate at either of two 
clock speeds: the standard Apple II speed of 1 MHz, or the faster 
speed of 2.8 MHz, When running programs in RAM the Apple HGS 
uses a few clock cycles for refreshing memory, making the 
effective processing speed about 2.5 MHz. System firmware, 
running in ROM, runs at the full 2.8 MHz. 



The 65816 registers are discussed 
in more detail In the Apple ISgs 
Hardware Reference. 



Transformable registers 

If you are an assembly- language programmer, note from Figure 
1-2 how the processor's registers change size to accommodate 
mode changes. The accumulator and X- and Y- index registers 
change from 8 bits to 16 bits in going from emulation to native 
mode. The stack pointer also becomes 16 bits long, meaning that 
in native mode the stack can be anywhere in bank $00; in 
emulation mode it is confined to page 1 of bank $00, The direct 
register is not used in emulation mode; in native mode it is the 
base address for all zero-page addressing modes, meaning that in 
native mode the Apple IIGS can have several zero pages (called 
direct pages), located anywhere in bank $00. 
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6502 Emulation Mode 
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Figure 1-2 

Program registers In the 65816 microprocessor 



For additional memory concepts. 
see Chapter 6 of this book For 
more complete Information, read 
the Technical introduction ta the 
Apple «ss. 



Expanded memory 

Thanks to the 24 -bit addresses of the 65816, the Apple II G 5 can 
access a total memory space of 16 megabytes. Of this total, up to S 
megabytes of memory is available for RAM expansion, and one 
megabyte is available for ROM expansion. The rest is not used. 

The minimum memory configuration for the Apple IIGS is 256K 
of RAM. Programs written for the Apple OGS — that is, programs 
that run the 65816 microprocessor in native mode (thereby 
gaining the ability to address more than 64K of memory)— can 
use up to about 176K of the 256K. The rest is reserved for displays 
and for use by the system firmware. 

* Note: If your application uses the Apple IIGS Toolbox — as this 
book strongly recommends — your application will have less 
than 176K of available space on a 256K machine. So if you are 
writing anything other than a very small program, the program 
will probably require an Apple IIGS with a minimum of 51 2K of 
RAM, 
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Basic configuration 



Expansion memory 



Bank-switched memory 



I/O memory 



For more Information on the 
memory configuration of 
standard Apple II computers, see 
the Apple He Technical 
Refor&nce Manual or Apple lie 
technical Reference Manual. 



Figure 1-3 

Apple lies memory map 

The basic 256K of RAM memory is mapped as four banks ($00, 
$01, $EQ, and $E1) of 64K each. As Figure 1-3 shows, portions of 
those banks are reserved for system use or I/O addresses, just as 
in other Apple II computers. 

The Apple IIGS has a special card slot dedicated to memory 
expansion. All the RAM on an Apple IIGS memory expansion 
card is available for Apple IIGS application programs. Expansion 
memory is contiguous: its address space extends without a break 
through all the RAM on the card. Expansion RAM on the 
Apple lies is not limited to use as data storage; program code can 
run in any part of RAM. 



Super Hi-Res video display 

The Apple IIGS gives you the most sophisticated high-resolution 
color display of any member of the Apple II family. Now your 
applications can mix dazzling color and sharp, 80-column text or 
precise line drawings on the same screen. And do it easily, with 
the help of built-in toolbox routines. 
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Hi-Res. Double Hl-Res, and other 
standard-Apple II video display 
modes are described in the 
Apple lie Technical Reference 
Manual and Apple He Technical 
Reference Manual. 



In addition to all the video display modes of the Apple He and 
Apple lie, the Apple IIGS has two new Super Hi-Res display modes 
that look much clearer than standard Hi-Res and Double Hi-Res. 
Super Hi-Res is also easier to program than Hi-Res or Double Hi- 
Res, because it maps entire bytes onto the screen, instead of .seven 
bits, and because its memory map is linear. 

Used with an analog RGB video monitor, the Apple IIGS displays 
high-quality, high-resolution color graphics. Table 1-1 lists the 
specifications of the two new graphics modes, 



Table 

Super 


1-1 

Hl-Rss graphics 


modes 










Mods 




Horizontal 
resolution 


Vortical 
resolution 


Bits per 
pixel 


Colors 
per line 


Colors 
on screen 


Colors 
possible 


320 
640 




320 
640 


200 
200 


4 bits 
2 bits 


16 

16* 


256 
256* 


4096 
4096 



"Different pixels in 640 mode use different subsets of the available colors. 



Pixel ts short for pfcfure element A 

pixel corresponds to the smallest 

dot you can draw on the screen. 



For more Information on using 
color, see * Drawing to the 
Screen" In Chapter 3. 



Each dot on the Super Hi-Res screen is a pixel. The screen image 
is either 320 pixels or 640 pixels across, by 200 pixels down, In 
memory, each pixel has either a 2-bit (640 mode) or a 4-bit (320 
mode) value associated with it. The pixel values select colors from 
programmable color tables. A color table consists of 16 entries, 
and each entry is a 12-bit value specifying one of 4096 possible 
colors. 

In 320 mode, each pixel consists of four bits, so it can select any 
one of the 16 colors in a color table. Its palette is all 16" colors in 
the color table. In 640 mode, each pixel is only two bits, so it can 
select from four colors only. However, the 640-mode color table is 
divided into four mini-palettes of four colors each, and successive 
pixels select from successive groups of four colors. Thus, even 
though a given pixel in 640 mode can be one of only four colors, 
different pixels in a line can take on any of the colors in a color 
table. 

To further increase the number of colors available on the display, 
there can be up to 16 different color tables in use at the same 
time, giving as many as 256 different colors on the screen. 
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RgUte 5-9 shows -the mcjc 
components o' the sound 
harciwa;e. 



r ur more in'ormafian on LffllftQ 
sound, see the section. "Waking 
Sounds' In Chapter G. S&e also 
the App'c S&s Hardware 
Reference to: details aboul I he 
sound system and ihs DOC, 



Digital sound synthesizer 

Like other computers in the Apple H family, the Apple lies can 
produce simple, single-bit sounds such as dinka, beeps, and toiieg. 

But it can also do a whole lot more. The Apple JIGS has a new 
digital sampling sound system buik around a special-purpose 
synthesiser TC called the Digital Oscillator Chip, or DOC for 
short. Using me DOC, the Apple 11GS can produce 15 voice music 
and other complex sounds without tying up its main processor. 

Tiie sound system consist* of the DOC, an audio amplifier and 
internal apoafcer, rt connector for an external amplifier and 
speaker, 64K of independent RAM for storage of sound samples, 
and a custom IC called the Sound GLU ^general l (J ^[ €: [m j0. The 
Sound GLU is the system intcrfatic to I he DOC, and also controls 
Jlit": volume of foe old-style single-bit output. 



I or more information en using the 
Apple Desktop Bus. soc- 
"Com-nuricathg with Flies and 
DcvJees" ifi Chapter b. See also 
the Appto Ugs Tonlhnx Q&fw$nc& 
GnU .App's ISgs I iardware 
Geferencs 



Detached keyboard with Apple Desktop Bus 

The new detached keyboard includes cursor keys and a numeric 
keypad. The Apple De.ski.op Bus, which, supports the keyboard and 
the Apple Mouse, can also handle other input devices such as 
joysticks and graphics tablets. 



Expansion slots and built-in I/O 

Tn addition to the memory expansion slot mentioned earlier, tire 
Apple 11CS has seven I/O expansion slots like those on an Apple 
He. Most peripheral cards designed far the Apple H Phis and the 
Apple lie work in the Apple fJGS slots. The Apple lies also has 
game I/O connectors for joysticks and other game hardware. 

Like the Appie He, the Apple TIGS has one built-in disk port and 
two serial J/O portw. The built-in AppleTalk interlace uses one of 
the serial ports. Programs can use either the built-in ports or 
peripheral cards in slots to perform input/output functions. 
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Built-in I/O features are accessed as though they were peripheral 
cards in slow. For most of the expansion slots, the user can 
choose Con the Control Panel) beiween using a peripheral c-Aid or 
using the built-in feature associated with the slot Table 1-2 shows 
the slot-equivalents for the built-in features. 

Table 1-2 

Applo lies expansion slois and Internal-part equivalents 

Slot Available mlsmal !»a1ur* 

1 serial purl (pttttter) 

2 M-nd pnrt tcomrmmicatiOils) 

3 flO-cuhinin disphiy firmware 

4 mouse support 

% SirwitPoU (disk Supptxl) 

ft t)isk U® Mippofl 

7 ApplcVslk stippnrl 



Clock-calendar and Control Panel 

The Apple UGS has a built-in real-time dock, 'llwj iisftf acta lh«j 

time and date with the Control! Panel, a ROM based program ihnl 
*]>'.> COIlfigutCK expansion slots, serial jJOrtSi display iiolorn, sound 
volume and pitch, and other options 

All Control Panel sellings, including the clock-calendar values, ;irc 
maintained in a special bauery-powered RAM that is maintained 
f.vr.n during power interruptions 



Compatibility with standard Apple II computers 

Although the Apple lies is more powerful than previous Apple II 
computers, It is still a member of the family. With the 
microprocessor in 6502 emulation mode, and with ihe ProOOS 8 
operating system active, nearly any ProDQS-8-based Apple II 
application runs just fine on the Apple Tics. The only noticeable 
difierencc is 3 2.5-umf:s increase in execution speed — antl even 
that difference can be eliminated if your software must run at the 
6502 clock speed, Furthermore, as just noted, most peripheral 
cards designed Tor the Apple II Plus or Apple He will function 
identically In the Apple IICS, 
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ProDOS 16 is the Apple HGSdisk 
operating sytem. It is 
documented In the Apple tkss 
PtoDOS 16 Reference. See also 

Chapter 6 of this book. 



Getting the most out of the Apple IIGS, however, requires 
execution in 6581 6 native mode under the more advanced 
ProDOS 16 operating system. That's what this book is about: 
writing programs that take full advantage of the computer. Under 
those conditions, existing standard-Apple II applications cannot 
run without at least some modification. If you have written a 
standard-Apple II application, see Appendix D for suggestions on 
how to modify it for native-mode operation under ProDOS 16. 



" 



The Apple desktop interface 

Desktop applications are programs of a particular style — a style 
that presents an accessible, nonlhreatening, and predictably 
consistent interface to the user. If your programs show these 
qualities, they will be easier to learn and more satisfying to use. 

The concepts behind this style of program constitute the Apple 
Human Interface Guidelines. This section will help you see what's 
involved in writing an application that follows the guidelines. 

Figure 1-4 shows some of the common visual features of a desktop 
application. The interface is graphics-based rather than text-based 
The screen itself represents the desktop, upon which documents 
appear in movable, scrollable, overlapping windows. Pull-down 
menus appear across the top of the desktop. Icons instead of text 
may represent certain concepts or objects, The user can 
manipulate the menus, icons, windows, and window contents with a 
mouse or other pointing device as well as with the keyboard. 
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Figure 1-4 

The Apple I less desktop 

These visual features are not the real essence oFa desktop 
application, however. The true importance of desktop applications 
lies in their relationship with the user, as explained next. 



Human Interface Guidelines 

If you are developing application programs for the Apple UGS 
computer, you are strongly encouraged to follow the principles 
presented in Human Interface Guidelines: The Apple Desktop 
Interface. That manual describes the desktop interface through 
which the computer user communicates with the computer and 
the applications running on it. This section briefly outlines a few 
of the human interface concepts. The Apple Desktop Interface, 
first introduced with the Macintosh computer, is designed to 
appeal to a nontechnical audience. Whatever the purpose or 
structure of your application, it will communicate with the user in 
a consistent, standard, and nonlhreatening manner if it adheres to 
the desktop interface standards. These are some of the basic 
principles: 

■ Human control: Users should feel that they are controlling the 
program, rather than the reverse. Give them dear alternatives 
to select from, and act on their selections consistently. 



The Apple desktop interface 
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■ Dialog: There should be a clear and friendly dialog between 
human and computer. Make messages and requests to the user 
in plain English. 

■ Direct manipulation and feedback: The user's physical actions 
should produce physical results. When a key is pressed, place 
the corresponding letter on the screen, Use highlighting, 
animation, and dialog boxes to show users the possible actions 
and their consequences. 

■ See and point (Instead of remember-and-type> The user selecfc 
actions from alternatives presented on the screen. In general, 
the process is in the order object followed by verb—thai is 
one selects first the object to be acted upon, and then the ' 
action to be performed. 

■ Exploration: Give the user permission to test out the 
possibilities of the program without worrying about negative 
consequences. Keep error messages infrequent. Warn the user 
when risky situauons are approached, but don't erect 
unnecessary barriers. 

■ Graphic design; Good graphic design is a key feature of the 
guidelines. Objects on the screen should be simple and clear 
and they should have visual fidelity (that is, they should look" 
like what they represent). Use familiar, concrete metaphors to 
represent aspects of the computer and program. The desktop is 
the primary metaphor in the Apple Desktop Interface. 

■ Avoiding modes: A mode is a portion of an application that 
the user must explicitly enter and leave, and that restricts the 
operations that can be performed while the mode is in effect 
By restricting the user's options, modes reinforce the idea that 
computers are unnatural and unfriendly. Use modes sparingly. 

■ Device-Independence: Make your program as hardware- 
independent as possible. Don't bypass the system-provided 
software tool sets and interfaces-^your program may become 
incompatible with Tuture products and features, 

■ Consistency: As much as possible, all your applications should 
use the same interface. Don't confuse the user with a different 
look for each program. 

■ Evolution; Consistency does not mean that you are restricted to 
using existing desktop features. New ideas are essential for the 
evolution of the Human Interface concept, If your application 
has a feature that is not described in Human Interface 
Guidelines, make sure it cannot be confused with an existing 
feature, U is better to do something completely different than 
to half-agree with the guidelines. 
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Aooendix B discusses how writing 
Apple lies desktop applications 
differs from programming for 
standard Apple II computers. 



Appendix A discusses how writing 
Apple IIgs desktop applications 

differs from Macintosh 
programming. 



Why write desktop applications? 

The biggest reason Tor programming desktop applications on the 
Apple IIGS is the consistent interface they present. Users spend 
less time learning and more time using an application if they 
already know their way around. 

There are some disadvantages to desktop applications. Apple IIGS 
desktop programs will not run on the Apple He and He. Because 
desktop applications require the use of graphics to support 
windows and multiple fonts, the interface can be slower than a 
simpler text-based command-line or menu interface. Also it takes 
time to learn the techniques of writing desktop applications. 

On the other hand, experience with the Apple Macintosh 
computer has shown that an interface that is consistent from one 
application to another is extremely attractive to users, because it 
dramatically cuts down the learning time for each new 
application. The Apple desktop and the Human Interface 
Guidelines have been refined over several years of studies and 
first-hand experience by Apple and independent developers. 

The cost to you in development time is minor when you consider 
the increase in your product's appeal due to ease of use and 
compatibility with the Macintosh interface. In addition, if you are 
an Apple U developer new to the Apple desktop, the techniques 
you learn (although not ihe actual code, in most instances) are 
directly applicable to the Macintosh. 



Event-driven programming 

In the old days of programming, all programs were executed in 
batch mode; the entire program was put on computer cards (or 
worse, punched paper lape) and fed into the computer all at once 
The computer executed the instructions in the same sequence 
every time ihe program was run (any conditional branching was 
controlled by data read in with the program), reading data and 
writing out results at specified points in the program. 

Batch mode was fine for "crunching data", but it wasn't very useful 
for applications (such as word processing or drawing) that require 
the user to make decisions while the program is running. When 
computer terminals were invented, programmers began writing 
programs that allowed users to send commands to Lhe computer 
and wait for responses — interactive programs were born. 



Event-driven programming 
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An 9 vent is o notification to ttie 
application of some occurrence, 
Interna! or external, ta which ths 
application may choose to 
respond. 



Any interactive program is in some sense event-driven. That is, 
the computer spends much of its rime waiting for some user input 
to occur, usually a key press. Traditional interactive programs, 
however, still largely control the choices and the sequence in 
which operations are performed. The user, who follows rather 
than leads, still feels that the program is in control. 

With the introduction of the Apple Macintosh and Lisa® 
computers, Apple's Human Interface Guidelines and event-driven 
programming came into prominence. The basic principle of 
event-driven programming is that there are many choices 
available at any time, and that the user controls the flow of the 
program. In a typical Apple IIGS program, for example, the user 
can select choices from a half-dozen menus, open or dose 
windows, use desk accessories, resize or move windows, or do 
some sort of work (such as word processing or drawing). With few 
exceptions, any of these operations is available at any given time. 

Events that cause a response by the program include key presses 
and mouse-button clicks, and might also include use of game 
paddles, insertion of a disk in a disk drive, data coming over a 
communication line, or even events generated by the program 
itself. 






The main event loop 

Although an event-driven program may at first appear extremely 
complex, its basic structure is actually quite simple. It spends most 
of its time waiting in a program loop called the main event loop. 
The only thing the program is waiting for is an event — any event 
When it detects an event, it determines the type of event, takes 
whatever action is necessary, and returns to the main event loop 
to wait for trie next event. 

Figure 1-5 is a conceptual representation of the flow of execution 
in an event-driven program, For most of the time, the taxi 
(program execution) remains in the event loop, circulating 
constantly, and stopping at the taxi stand (the event queue) each 
time to see if there is a wailing passenger (an event). The taxi takes 
passengers in order, one at a time, to their respective destinations 
(various event-handling subroutines), The taxi wails out front while 
the event is being handled (execution temporarily leaves the 
event loop), then proceeds around the loop once more to pick up 
another passenger. Circulation continues until the program ends. 



1*3 
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Figure 1-5 

The main event loop 

For a more specific example, assume that the program is a word 
processor. From the user's point of view, any of a large number of 
operations are available, from typing a character to reformatting 
the entire document to setting control-panel options. The main 
event loop, however, need wait for only two types of events: 
mousc-bu non-down and key-down. 



Event handling 

To illustrate how a program handles an event, let's suppose that 
the user decides to select an item in a window titled CORTLAND 
Csee, for example, Figure 1-4) that is open on the screen but not 
currently active. The user moves the mouse to the inactive window 
and clicks the mouse button. When the program detects the event, 
it handles it like this: 



Evenf-drlven* programming 



15 






1. What kind of event was it (mouse-down, key-down, and so 
forth)? 

Mouse-down 

(At Lhis point execution leaves the main event loop to handle 
the event.) 

2 Was it in a window, on the menu bar, or neither? 
Window 

3. Was it the active window or an inactive window? 

Inactive 
4 Which inactive window? 

CORTLAND 

5, Make CORTLAND the active window, 

6. Return to the main event loop. 

Why return to the main event loop now instead of going to a loop 
that can handle events that can occur only within the active 
window? Because the user might change his mind and decide to 
open a menu, select a different window, or even quit the program. 
If you return to die main event loop as soon as possible, the user 
retains the feeling of being in control of the program. 

The structure of an event-driven program can be fundamentally 
different from that of other types of applications. Its principal 
subrout.nes are organized by events to handle ("mouse-down " 
'key-down'), rather than by the specific tasks the program was 
written to perform ("text entry," "drawing"). Chapter 2 illustrates 
this difference in detail. 

The Apple IIGs provides a large number of software tools that 
make it easier for you to write an event-driven program. The 
Event Manager performs the bookkeeping that makes your 
program's main event loop work— it gathers events, determines 
T u . eir lypcs - and P'aces them in order, for vour nrooram in 

SSSr? ' deSCHbed ln handlc - A «*'>» «"** «lfcd r«^„r»u£Sly utkes 

care of sample event-handling such as resizing or moving a 
window. Then it passes the information on to your program. 

We'll look at events in much greater detail as we go along. Chapters 
2 through 5 describe the sequence of tool calls and procedures that 
an event-driven program must execute on the Apple IIGS and 
Appendixes E through G present source code for such a program i 
three different programming languages (assembly language, C, and 
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The Apple IIGS Toolbox 

Trying to write a desktop, event-driven application without the aid 
of some powerful system software could be quite difficult. 
Fortunately, the Apple IIGS comes equipped with a software 
(oolbox, which contains a complete complement of tool sets 
designed to make your job easier. 

The Apple IIGS tools support the standard desktop interface and 
provide you with building blocks to help you construct your 
application. 



Pen size and pen mode are 
discussed under 'Drawing to the 
Scram." In Chapter 3. 



Manager is simply another name 
taffoctfsef. 



What is a tool set? 

A tool set in the Apple IIGS environment is a collection of 
related software routines that provides one major capability. Kach 
routine within a tool set performs a fundamental operation. For 
example, the QuickDraw II tool set provides routines that handle 
graphics on the Apple IIGS. Within QuickDraw II, SeiPenSise and 
SetPenMode are routines that set the pen size and pen mode. A 
routine may take one or more specific parameters as input and 
yield one or more values as output. 

The tool sets, then, are groups of related routines that perform 
many common tasks and are always available for your 
application's use. Taken together, the tool sets are very similar to 
the Macintosh toolbox. Many of the capabilities of the Apple IIGS, 
even those not directly related to desktop applications, are easily 
accessed through the tools. For example, both the Memory 
Manager (which allocates all Apple IIGS memory) and the Event 
Manager (which controls event-driven programs) are tool sets. 



The Apple Hss Toolbox 
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Vou can even use the Tool 
Locator to access a tool set you 
have written yourself, See 'User 
Tool Sets* in Chapter B, 



Why use tool sets? 

Making use of tool sets allows you to concentrate on your 
application's specific business rather than on background work. 

A number of the tools are in ROM They are therefore available tc 
all programs without using disk space. Additional tools are 
available in RAM, but you needn't worry about where a particular 
tool set or routine is. A tool set called the Tool Locator, which 
enables tool sets and applications to communicate, takes care of 
the necessary bookkeeping functions. All you need to know is the 
name of the routine and how to call it in your programming 
language. 

Tool sets insulate your program from the details of machine 
hardware. If the program accesses a hardware feature with a tool 
call, die program will remain compatible through future versions 
of the Apple HCS, even if the hardware feature changes. 

The tools thus provide an abundance of capabilities at a 
minimum cost in programming time and memory space. Their 
bookkeeping functions are almost automatic, the interface to them 
is simple, and the applications you write will not be rendered 
obsolete by future changes to the hardware. 

■"• Note; Many of die Apple IIGS tool sets are independent of the 
operating system. They are thus available for any Apple IIGS 
application, regardless of the operating system it is written for, 

To get an idea of the range of capabilities of the Apple IIGS 
Toolbox, it's useful to group the tool sets into categories. The 
arrangement given in Figure 1-6 is arbitrary; as you get to know the 
tools better, you may prefer other groupings. 

Brief explanations of the tool sets within each category follow. The 
tool sets are described in more detail in Chapters 3 through 6 
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QuickDraw II 
QuickDraw II Auxiliary 
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System Loader 



Integer Math Tool Set 




SANE Tool Set 



Sound Tool Set 



Note Synthesizer 



Note Sequencer 



Figure 1-6 

Apple lies tool sets 
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The five basic tool sets 



yhich 



"Hie five tool sets listed below provide the framework upon wl 
the other tools can build. All of these tool sets must be used in 
every event-driven application: 

■ Tool Locator: Handles all tool calls. This tool set relieves you 
of having to know where in memory any tools resides; the Tool 
Locator finds and passes execution to the proper routine when 
you make a tool call. Once you start the Tool Locator, its 
operation is automatic. 

■ Memory Manager: Allocates memory for use by the 
application. When your application needs memory, it must 
request it from the Memory Manager. 

■ Miscellaneous Tool Set Includes mosdy system-level routines 
that must be available for other tool sets to use. 

■ QuickDraw II: Controls the graphics environment and draws 
basic graphic objects and text on the screen. QuickDraw U 
Auxiliary is an extension to QuickDraw II. Other tool sets call 
QuickDraw II and QuickDraw II Auxiliary to draw such things as 
windows and icons. 

■ Event Manager: Receives events as they happen, maintains a 
queue of events, and passes events on to the application. 



Desktop -interface tool sets 

Tools in this group support the desktop interface. You will almost 

always use the Window Manager and Menu Manager in desktop 

programs; you should use the other tool sets if your application 

needs iheir features (for example, you need the Dialog Manager if 

your application uses dialog boxes). Many of these tools are also 

The list of tool sots need go: to needed to support desk accessories. 

support desk accessories Is given 

h Table 6-1. ■ Window Manager; Creates and updates windows, keeps track of 

size changes and overlapping. 

■ Control Manager: Implements controls — objects on the screen 
such as check boxes — which the user can manipulate with the 
mouse to cause instant action or to change settings. 

■ List Manager: Along with the Control Manager, handles 
ordering, display, and selection of lists of selectable items in 
windows. 
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■ Dialog Manager: Implements dialog boxes, which your 
application should place on the screen when it needs more 
information to carry out a command. 

■ LineEdit Tool Set Presents text on the screen (usually in dialog 
boxes), and allows the user to edit that text in limited ways. 

■ Menu Manager: Controls and maintains pull-down menus and 
the items in the menus. 

■ Font Manager: Provides fonts in a variety of sizes and styles for 
QuickDraw II to use when it draws text, 

■ Scrap Manager: Supports the desk scrap, data to be copied 
from one application to another Cor from one place to another 
within an application). 

■ Desk Manager: Enables applications to support desk 
accessories, mini-applications that can be run at the same time 
as another application. 



Device -interface tool sets 

Tools in this group manage input and output between the 
computer and peripheral devices. 

■ Print Manager: Carries out page-setup and printing commands 
from the user. Provides an interface between the application 
and printer drivers. 

■ Standard File Operations Tool Set: Presents dialog boxes to the 
user when a file is to be saved or opened. Provides a 
standardized interface between the user and ProDOS 16. 

■ Apple Desktop Bus Tool Set: Provides access to Apple Desktop 
Bus commands. The Apple Desktop Bus transmits signals to 
and from the keyboard, mouse, and other input devices. 

■ Text Tool Set: Allows applications running in native mode to 
access Apple II character device drivers, which require the 
processor to be in emulation mode. 
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Operating-environment tool sets 

Tool sets in this group control low-level hardware and software 
functions. The Memory Manager and the Miscellaneous Tool Set 
listed under "The Five Basic Tool Sets," can also be considered 
part of this group, Other members are: 

■ System Loader: Loads all program and data segments into 
memory. 

■ Scheduler: Allows more than one program to access system 
resources that normally cannot be shared, 

I 



Specialized tool sets 

Tool sets in this group perform various specialized functions, as ! 
listed. 






Sound generation 

These tools make it easy to take advantage of the advanced so 
capabilities of the Apple IIGS. 

■ Sound Tool Set: Constitutes the sound hardware's interface to 
the Apple IIGS Toolbox, and provides basic sound 
manipulation routines. 

■ Note Synthesizer: Facilitates creation of musical notes 
simulating a variety of instruments. 

■ Note Sequencer: Strings together notes from the synthesizer 
into the sequences, patterns, and phrases that make up a tune. 






Mathematical computation 

These tools perform mathematical functions and calculations. 

■ Integer Math Tool Set: Provides mathematical routines that 
manipulate integers, long integers, and signed fractional 
numbers. Also converts numbers to hexadecimal and decimal 
ASCII strings, 

■ SANE Tool Set: Implements the Standard Apple Numerics 
Environment, which provides extended- precision floaling-prjti 
arithmetic that conforms to IEEE standard 754. Supports 
multiplication and division and trigonometric and other 
transcendental functions. 
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Load file* are programs In 
machine-executable format, See 
thBApptal&S Programme's 
Watkshop Reference fat 
information on the file format lor 
program segmants. 



See the Apple IIGS ProDOS 16 
ffefereneefor complete 

Information on ProDOS 16 and the 
System Loader 



Seetnedpp/e IIGS Toolbox 

R&ferenc&for complete 
Information on the Memory 
Monager. 



Program segmentation 

Another powerful feature available to Apple IIGS programs is that 
they can be segmented, and the segments can be relocatable and 
dynamic. A segmented program is divided into chunks that can 
be loaded into memory piecemeal. A relocatable segment is a 
piece of code or data lhat needn't be put at any particular 
memory address in order to function correcdy. A dynamic 
segment is one that is not loaded unLil it is needed during 
program execution. 

Segmentation of executable programs (load flies) gives two 
principal advantages; (1) your program might fit into a smaller 
memory space to help it run in small-memory machines and 
under application-switching programs, and (2) it might load and 
start to execute more quickly. Both advantages occur because less- 
needed segments can be made dynamic and left on disk until they 
are actually called into use. Furthermore, on the Apple IIGS 
computer no single block of code can occupy more than 64K 
bytes of contiguous memory. To load a larger program than that, 
you must split it up into two or more load segments. 

Making your load-file segments relocatable means lhat Lhe 
available memory in the computer can be allocated eificientfy 
among multiple programs (including system software and desk 
accessories), 

Segmentation works because the Apple IIGS Memory Manager and 
System Loader tool sets, work together with ProDOS 16, the Apple 
IIGS operating system, to execute, move, and remove program 
segments in a fashion that is sophisticated yet totally transparent 
to the program user (and in many cases to the programmer too). 
The Memory Manager takes care of assigning each segment to a 
block of memory; the System Loader keeps track of where in 
memory the segment has been loaded, and patches intersegment 
calls in each segment as it is loaded. ProDOS 16 controls 
execution of the programs once they are in memory. 

Chapter 6 presents a more detailed discussion of load-segment 
structure and how the Memory Manager, System Loader, and 
ProDOS 16 interact to make it all work. 
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Patching Is the process of 
modifying code once it Is In 
computer mBmory, 



Absolute and relocatable segments 

To make efficient use of memory with segmented programs, Lhe 
Memory Manager and System Loader need to be free to place 
code and data segments where they choose. 

Absolute code is computer code that must be loaded at a spe> 
address in memory and never moved- Many standard Apple II 
programs contain absolute code. The programmer decides whe 
the program will sit in memory, and designs all address 
references and subroutine jumps accordingly, 

Relocatable code is computer code that contains relative and 
symbolic address references, and so can execute correctly 
wherever it is placed in memory, See Figure 1-7. Once it is in 
memory, relocatable code must be patched by the loader so that 
its address operands contain the proper values. 

For efficient memory use, it is very important that as many 
segments as possible be relocatable, The Memory Manager must 
be free to place segments so they will not conflict with each other 
and so that contiguous areas of free memory are maximized. 
None of your program's segments should be absolute. 
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Absolut© and relocatable segments 
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See Chapter 6 for more 

Information on how static and 
dynamic segments ar& loaded. 



Static and dynamic segments 

A dynamic segment is a load segment that can be loaded and run 
automatically during program execution, The application itself 
needn't do any loading — whenever the application calls a routine 
that is in a dynamic segment, the segment Is automatically loaded 
and executed. Furthermore, that dynamic segment is not 
subsequendy unloaded from memory unless the application 
permits it, and even then only when the memory is needed for 
something else; in most cases the segment remains instandy 
available the next time it is called. 

A segment that is not dynamic is static. A static segment is 
loaded at program startup, and is not unloaded or moved during 
execution. The main segment of any program is static; any other 
segments may be static or dynamic. See Figure 1-8. 

The question of which segments to make static and which ones to 
make dynamic is not as easily answered as the question of 
absolute and relocatable. At least one segment in each program 
must be static; if the program is small, that single segment may 
constitute the entire program. But if the program is large or if it is 
designed to require little memory, many of its segments may be 
dynamic. 

Making as many segments dynamic as possible can also decrease 
the time required to initially load and start up a program. On the 
other hand, there may then be momentary delays during 
execution, as the dynamic segments are loaded when called. 
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An object file is a program that 
has passed through on 
assembler or compiler, if contains 
machine-language code. 

Chapter 6 shows you how fo 
specify object segments and 
iood segments 



A source file is □ program in Its 
original text form . as written by the 
programmer, 



The Programmer's Workshop 

To help you write application programs that make the most of 
new Apple IIGS features, Apple has produced an integrated 
development environment called the Apple IIGS Programmer's 
Workshop (APW for short). 

APW helps you create event-driven, segmented desktop 
applications that access the full power of Lhe Apple IIGS Toolbox. 
With APW you can write modular source-code segments in a 
variety of high-level and low-level programming languages, and 
then combine them into a single functioning program. 

APW's object files and load files follow a file specification called 
object module format <OMF). OMF was developed, in part, to 
create a system in which program segments written in several 
languages could be combined and run together, because they all 
would have one uniform object file "language '. With OMF you 
can optimize various routines by writing them in different 
languages and combining them into a single program, A routine 
written for a program in one language can be dropped into 
another program in another language, without modification, 

Figure 1-9 is a simplified picture of what takes place from writing 
to running an application under APW. 

1. A program is first created as a source file, using a text editor 
appropriate for the language(s) involved. APW includes a full- 
Featured, multi-language text editor. 

2 The source file, in ASCII text form, is then cither compiled or 
assembled to produce an object file. Directives in the source 
file control whether and how the object file is to be segmented. 
A single source file can be compiled into more than one 
object file. 

3. The object file is converted by a linker into a load file. 
Directives in the original source file, as well as commands to 
the linker, can control segmentation in the load file. More than 
one object file can be combined into a single load file. 

4, In the final step (if all goes well), the load file runs correctly wh( 
the loader places it in memory and it is executed. In the early 
stages, of course, program development usually involves at least 
some time with a debugger such as the Apple IIGS Debugger, 
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Figure 1-9 

Steps in creating an application 

Using APW Lo design and write segmented programs is covered in 
Chapter 7. But before we get too deeply into ihe bow of Apple 
IKS programming, we'd like to show you some more of the what 
and why. The next five chapters present an extensive 
programming example and give some additional background, 
showing what Apple lies programs can do and why they go about 
it in the ways they do. 
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Chapter 2 



Hodgepodge: A Sample 
Event-Driven Application 
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Now that you've had an overview of the Apple IIGS and 
programming concepts, Jet's plunge right into an example. 

This chapter explores a demonstration application developed by 
Apple, called HodgePodge. HodgePodge has a recommended 
organization for evem-driven, desktop applications on the Apple 
IIGS. We walk you through the program, presenting the code 
explaining it in detail as we go along, 

You may wonder why we're dissecting the sample program so 
soon — after all, much of its structure and most of its tool calls i 
parameters aren't explained until later in the book. Our hope i 
that, given the general concepts already presented and the i 
sive commentary accompanying these listings, your quickest re 
to understanding is to see actual code from a functioning program 

On the other hand, Lhere is no required reading order for this 
book. If you want to delve deeper into toolbox concepts before 
looking at code samples, by all means skip ahead to Chapters 
through 5. Come back to this chapter when you're ready. 

Don't forget to look in Appendixes E, F, and G for the compten 
source-code listings of HodgePodge in all three languages 
(assembly language, C, and Pascal). And, whichever order you 
read things in, don't forget to try HodgePodge in action on yo 
Apple IIGS! 



What HodgePodge does 

HodgePodge is a short application that loads stored graphic 
images (picture files) from disk and displays them in movable, 
scrollable, resizeable, overlapping windows on the screen. It ali 
displays, in windows, text samples of the various fonts available i 
your system. See Figure 2-1. 

Like a proper desktop application, HodgePodge shows menus, 
displays messages in dialog boxes, supports desk accessories, 
stores and retrieves files, prints text and graphics, and even 
provides an "About HodgePodge" dialog box accessible from 
Apple menu. 

If you have a copy of the sample program, put it in your computi 
and run it now. On the disk that accompanies this book, it's the 
application named HP, in the folder for any of the three languaj 
(There are three files named HP — one for each language.) 
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Figure 2-1 
HodgePodge desktop 



Hodgepodge's menus 



HodgePodge displays five pull-down menus from a menu bar at 
ihe top of the screen: Apple menu, File menu, Edit menu, Windows 
menu, and Fonts menu. Within each menu, items that the user may 
select appear in black; items that the user may not select are 
dimmed (gray). When the user selects an item on a menu, lhat 
menu's title is highlighted until the selected task is completed. 



New desk accessories are 
described under "Supporting 
Other Desktop Features" in 

Chapter 5. 




Apple menu 

The Apple menu is a standard menu that all desktop applications 
should have. Its title is a small, colored Apple icon. The first item 
in the Apple menu is "About HodgePodge." Selecting it brings up 
a dialog box that explains a bit about the progam and its authors. 
"About" dialog boxes are typical of desktop programs. 

The Apple menu also lists the new desk accessories available on 
the user's system. 
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The Clipboard and fhg concepts 

of cut, copy, and paste are 
described under "Supporting 
Other Desktop Features' In 
Chapters. 



File menu 

should have. Here it contains seven items: 

■ Open: Opens a picture file and displays it in a window. 

■ Close: Closes the frontmost or active window, 

■ Save As,- Allows the user to save a picture window with its 
present filename or under another name. 

■ Choose Printer: Allows the user to select a printer. 

■ Page Setup: Lets the user «t certain parameters for printing. 

■ Print: Prints the contents of either a picture window or a font 
window. UHt 

■ Quit: Shuts down the program. 

AH of the items in the File menu are standard, but their 
implementation in some cases is specific to HodgePodge. 

Edif menu 

The Edit menu is a standard menu that all desktop applications 
should have. Here it contains five items: appucarjons 

■ Undo: Allows the user to reverse the last action undertaken. 

■ Cut; Deletes the selected part of a document and places the 
selection in the Clipboard. 

" SCT " C ° Py ° f '^ ***** Part ° f B d ° CUmcnt in the 

■ Paste: Copies the contents of the Clipboard into a document 

' SJSSS a selecced parl of a docmt ' w,thout ■*<*■ 

HodgePodge itself does not use the Edit menu; however the Edit 
menu must be present in case a desk accessory that needst is 






Windows menu 

The Windows menu ,s nothing but a list of HodgePodge 'a 
currently open windows, The list is arranged in L order in which 

t ££? "'" 0Pened ScleCUng ^ ™* of - window from 
me W ndows menu causes fet wjndow * 

any other open windows on the desktop. 
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Fonts menu 

With the Fonts menu, the user can display a piece of sample text 
using any font on the system, in any size and with any desired 
styling variation (such as bold or italic). Selecting the first item on 
the menu brings up a dialog box with which the user selects the 
font to display, and then draws the text in a window. Selecting the 
second item toggles the display of the next-opened font window 
between proportionally spaced and monospaced display. 



Hodgepodge's picture windows 

HodgePodge retrieves, displays, and stores color pixel images in a 
particular type of picture file. The user may open a file, view the 
picture, and then save the file again with the same or another 
name. 

With picture windows, HodgePodge demonstrates how to create 
windows and how to display images on the screen. It also shows 
an example of file access and demonstrates color printing. Figure 
2-2 is an example of a picture displayed in a window. 




Figure 2-2 

A HodgePodge picture window 
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Hodgepodge's font windows 

HodgePodge displays sample text in windows on the screen. '_ 
text may be in any point size and may have any combination i 
styling variations such as bold, italic, or underline. The text m; 
be in any font available on the user's system. The actual lines 
text that are displayed are specified in HodgePodge; the user 
cannot alter them. 

Many different font windows, with different sizes and styles, 
be open simultaneously. Unlike picture windows, font windows 
not opened or saved as files. 

With font windows, HodgePodge demonstrates how to create 
windows and how to draw text on the screen. Figure 2-3 is an 
example of a font window display. 
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Figure 2-3 

A HodgePodge font window 



How to use the sample program 

The sample program serves two purposes. First, it provides a rea 
framework within which to describe how Apple IIGS applications 
operate and how they should be written. Second, it provides you 
with source code modules that you can adapt to your own 
purposes on your own programs. You are encouraged to use at 
modify any applicable parts of HodgePodge for any programs 
you write. 
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Because you may be writing programs in any of various available 
Apple I1CS languages, we provide the sample program in three 
languages-assembly language, C, and Pascal. Complete source 
code listings are in Appendixes E through G. The parts of the 
program listings reproduced in Chapters 2 through 6 are in 
Pascal. 

♦ HodgePodge versions: Source code and executable forms of 
HodgePodge, in all three languages, arc on the disk that 
accompanies (his book. Sightly different versions of 
HodgePodge, with different features, have been distributed 
through other sources such as APDA. See Chapter 9. 



See Appendix D for a complete 
listing of HodgePodge 
subroutines. 



Organization 

The source code for HodgePodge consists of many individual 
subroutines in several separate files. Figure 2-4 shows the overall 
organization of the principal routines. The main program (on the 
left) calls each of the principal subroutines (on the right) in 
order, from top to bottom. 



Main program 
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Quit 
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Main even t loop 
MoinEvenl 



ShutDownTods 



Figure 2-4 

HodgePodge organization (simplified) 
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Hodgepodge's main event loop 
is described under 'Cycle 

Through the Main Event Loop.' 
later In this chapter, 



The most general routines, versions of which will probably app 
in every desktop program you write, are more heavily shaded; 
Hodgepodge, StartUpTools, SetUpMenus, MainEvent, and 
shutD own Tools, Most execution time is spent in the main ever 
loop (MainEvent) and in the subroutines that it calls. 

Smaller versions of Figure 2-4, highlighted to show particular 
subroutines, accompany discussions of the principal parts of the 
program. Another set of subroutine diagrams, starting with 
Figure 2-5, shows the flow of execution within and from the main 
event loop. 



Pascal HodgePodge was written 
In TML Pascal™ for APW. See the 
Bibliography. 



Code-listing convention 

The HodgePodge source code listings in this chapter and 
Chapters 3 through 6 are in Pascal. In addition to the standard 
Pascal syntax and notation, please note the following conventions: 

O Toolbox calls are in boldface. 

D Reserved words (such as if, then, begin, end, goto) are in itaDcs, 

□ Names of functions, procedures, types, and user-defined 
constants begin with capital letters, 

D Names of variables, fields within records, and toolbox-defined 
constants begin with lowercase letters. 

D Boolean values (such as TRUE and FALSE) are all capital 
letters. 



HodgePodge 



HodgePodge at a glance: 
the main program 

Briefly, HodgePodge (and any event-driven application) follows 
this sequence of operations when it executes; 

L It starts up; 

□ It initializes variables and data structures. 
D It starts up the tool sets. 

□ It sets up the program's menu bar. 

2. It continually cycles through the main event loop. 

3. As necessary, it handles application- specific events, 
4 Finally, it shuts down. 
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Iha HodgePodge main program 
1$ in the source file HP.PAS, 



program HodgePodge ; 

{.] 

{■ 

(■I 

begin 

InitGlobala; 

if StartUpToola then 

SetUpDe fault , ■ 
SetUptfenua; 
SetUpWindows ,- 
HainEvent; 
end; 



ShutEtawnTools; 



end, 






Most of the above tasks are carried out in subroutines, but they arc 
controlled by the main program. It is very short; this is what the 
Pascal version looks like: 



(begin HodgePodge..} 

USES and other declarations} 

(Initialize our globals, wemus, etc.) 

(if all tool sets loaded 0K~) 

( Set up print record) 
(Set up menus} 

(Set up windows) 
(Use the application.} 

{Shut down IIGS tool seta) 
(End of HodgePodge} 

Subsequent sections lead you through the principal subroutines 
called from the main program. The subroutines cover the steps 
common to most applications — setting up, handling events, and 
shutting down. 

The details of bow HodgePodge performs its own specific tasks, 
such as displaying fonts or pictureSj are mosdy left for later 
chapters. Here we are more interested in how HodgePodge 
illustrates the general independence of form from function in 
event-driven programs. That is, from a general point of view most 
desktop applications look pretty much the same. 



Step 0. Set the stage 

The source code for a typical desktop application begins with 
statements that bring in needed library files, sets up the operating 
environment, and perhaps defines some data structures. Many of 
these statements control what happens when the program is 
assembled or compiled, rather than when it executes. 



Step 0, Set lbs stage 
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Q For assembly-language programs, this category includes such 
casks as aefeeting long or short registers, loading macro 
libraries, and. initializing various toolbox data structures with 
using directives. 

Li For higher-level programming languages, Ihis category may 
include defining variable tyj>es, dimensioning arrays, and 
loading library Hies. 

Reier to Appendixes E ih rough C for details. 






Many constants and data structures are predefined in ihe interface 
libraries to the Apple IIGS Toolbox, and thus need not be defined 
within an application, 'lhey include formats and tie Id names for 
toolbox records and templates, and predefined constants fur 
values such as event ctxles and memory-block attributes. We'll 
discuss tlitLsc and other data structures as we encounter them in 
I iodgePodge. 




Step 1 . Start the program 

With the preliminaries out of the way, let's look at program 
execution. To Start a desktop program off on the right fool, you rifts 
to initialise any prog ram -specific variables and data structures yisll 
are going to use, start up the tool sets, and set up the system inenir 
bar, 






Initialize variables and data structures 

Where and how you define your data and data structures depend 
upon your program's purpose, the language you're using, and you: 
personal preference, 

Pascal llodgePodgc ha* three subroutines called early in progfam 
execution to set up initial values of imporiant components of the 
program Even [hough two of these routines are actually called 
ajlsr 100! startup (as Figure 2-4 shows), all three are grouped here 
for simplicity. In general, your programs will do some 
initialization before starting tools, and some after. 

T.;nlike several of the HodgePodge routines described in this 
chapter, these initialization routines are a pp plication-specific:; 
your program may have very different ones. 
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- inllGlobals 


'" !_ 




\ i 


- SetUpDefault 




-i 




- Set Up Windows 


j } 


1 








I— i 



InllGlobals Is In the source file 
GLOBALS.PAS. 



*■ NOte: The initialization routines InitGlobalsand 

Setupwindows do not appear in ihe assembly-language and C 
versions of HodgePodgc. In those languages, variables can be 
initialized as they are defined in the source file, rather than 
during execution. 

InitGlobals 

InitGlobal3 is the first routine called from the main program. 
It initializes several variables and text strings used later in the 
program; we will not describe them individually here. It also 
defines the text strings that constitute HodgePodge's menus. (The 
unusual formatting of the menu strings is explained under 
"Making and Modifying Menus" in Chapter 5.) In addition, 
InitGlobals creates a large colored Apple icon that is 
displayed in the "About HodgePodgc" dialog box (Figure 4-14). 



procedure InitGlobals; 

begin 

with plsWtTwp do 

begin 

S«tB*ct (dtBoundsRect, 120, 30, 520 , SO) ; 

dt Visible :-TK0E; 

dtRefCon :-0; 

dtItemList[0] ; -pointer (0) ; 

dtIt«nList[lI :=MIL; 
end; 



(begin InitGlobals-.} 

(template for "Please wait..." dialog} 

( — format defined by Dialog Manager} 

I set its size} 

(make it visible} 

(no special info here} 

(we'll insert this pointer later} 

{this terminates the item list} 



(Now define the text of HodgePodge's 

menu titles and i tenia I } 



AppleMenuStr 



FileMenuStr 



concatC»@\N3D0x\0\ 

' =About Hodge Podge. . .\N301\0' , 
' \N302D\O . ■ } ; 

concatC» File \N4 00\0\ 

■Open. . -\N401*Oo\0', 
'— Close\N255D\0 , J 

•Save Aa...\N403D\0\ 

— \H4040\0*, 
1 — Choose Printer. . .\N405\0*, 

=Page Setup, . .\N406D\0' , 
'=Print . . . \H40T *PpD\0 ' , 
'—- \N40BD\0\ 
' — Quit\N409*Qq\0 . ' ) ; 



Step 1 . Start the program 
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EditMenuStr 



WindowKenuStr 



FontWenuStr 



co-catl 1 ^ Edit \N50GD\Q', 
h ==Undo\N2SG*Zz\0', 
'— \N501D\0\ 
'■=-Cut\N251»SCx\0', 
' ==Copy \N2 52 *Cc \ * , 
' —Paste\N253*Vv\0 ' , 
■— Cleax\N254\0, ') ; 

concatl'» Window \N6Q0D\Q', 

■== No Windows AllQcated\N€0;D\C. ' ) ; 

concat('» Fonts \N7Q3\CP, 

"==Display Font. . .\N7Ql*Ff\0" , 

'—■Display Font as Mono-spaced\NV02 i Mm\D. ' ) ; 



lastWindow ;■= NIL; 
noWindStr := 



raor.oStr 



proStr 



' -=No Windows Allocated\NGOlD\D. >; 
■»=Display Font as Mono-spaced"; 



'==Display Font as Proportional'; 

isMonoFont := FALSE; 

with desiredfont do 

beg j r. 
famNum :- 5FFFE; 
fontStyle :- 0; 
fontSize :- 8; 

end,- 
wlndex ; = 0; 



SotKfiet (Applelcon.boundsRect, 0, 0,64,34) ; 
HP St uf f Hex ( @App 1 e I con . data [ 1 ] , 

'OO00O0O0O000ODOO0O0O0O0O0000D0O0" ) ; 

HFStuf f Hex (Mppleleon , data [2] , 

' OFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFCl ( > ; 

(- 
(. 
M 



(Now initialize other variables, 
records L strings:} 

{window Dointer] 



(item for Windows menu} 
(Item for Fonts menu} 
(Item for Fonts menu I 
(start fonts as proportional} 



{set default font characteristics: J 

{family number:) 
{plain text) 
{e pt.) 

{WIndftx is the, number of open windows} 

(Last, define the colored Apple icon 
to appear in the "About,,," box:) 

{siae of icon) 

{HPStuffHex puts pixel values in array} 



define each pixel of the) 
icon (see Appendix G) } 
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HPStuff Hex O Apple Icon, data [33) , 

■OFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFO' ) ; 

liFStU f f Hex (eAppIelcon . dat a, [ 34 1 , 

'0000000D0000000OCl000000O00D00000 , ) I 



and; 



(End of InitGlobala} 



SatUpDefault Is in the soutc© file 
PRINT. PAS. 



procedure SetUpDef ault ; 

begin 



SetUpDefoult 

SetUpDef suit creates a default prim record. (PrRecHdl is a 
handle-type, that references a Print Manager print record.) 
SetUpDef ault must be called after tool startup because it makes 
Memory Manager and Print Manager calls. 



printHndl ;- FrRecHdl (NawHandl* (140, 

irryMemorylD, 

att rNc-Cro s s+att rLocked , 

Ptr (0) ) ) ; 



FrD*fa.ult (ptintHndl) 



end; 



tbegin SetUpDefault...} 



(allocate memory for print record} 

(with our ID) 

(and the3« attributes' 

(no location restriction) 

{fill record with default values} 

(end of SetUpDefault} 



Setup Windows Is In the source file 
WIN DOW. PAS. 



SetUpWindows 

SetUpWindows sets initial window size and position on the 
screen. It is called after tool startup, although in this particular 
case it could just as easily have been part of InitGlobals, 



procedure SetUpWindows ; 

begin 

wXoffset ;- 20; 
wYoffaet :- 12; 
S*tB»Ct[iSizPoa,l 0,2 0,350, 80); 

end* 



{begin SetUpWindows...} 



(set initial window position} 
(from top left corner of screen) 
(the window's port rectangle 1 
(End of SetUpWindows) 



Step 1 . Start the program 
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- StortUpTools j 



StaftUpTools is In the source file 
HP. PAS. 



Start up the tool sets 

Proper initialization, especially for the Apple IIGS Toolbox, is i 
critical for successfully running an application. For that reason 
you are urged to simply adopt the following code for your o? 
programs. It works. 

In HodgcPodge, tool startup is in the subroutine StartUpTool 
called from the main program right after InitGlobals. The 
steps are shown here in the order in which they are executed i 
HodgePodge. Although that is not always the precise order in 
which ihey must appear in your own source code, tool startup 
order is in general very important. If you change the order 
without knowing exactly what you are doing, your program may| 
crash. 

The tool startup subroutine peforms three essential tasks: 

1. It loads the absolutely necessary tool sets — the Tool Locator.j 
the Memory Manager, the Miscellaneous Tool Set, QuickDraw 
II, and the Event Manager 

2. Using a tool table and a single LoadTools call, it loads all i 
other tools Hodge Podge will need. 

3- It starts up those just-loaded tools, in proper order. 

♦ Note: Many of the startup calls shown below require inputs or) 
return results. Look at the discussions of individual tool sets i 
Chapters 3 through 5 for more information; see the Apple I1C 
Toolbox Reference for complete explanations. 

Start UpTools begins by starling up the five basic tool sets. It 
also reserves some memory space {direct-page space) needed I 
several of the tool sets, 



function StartUpToola : Boolean; 



ponst TotalDP - SBOO 
DPForQuickDraw - $000 
DPForEventMjir = $300 

DPForCtlMgr 

DPForLineEdit 

DPForMenuMgr 

DPForStdFile 

DPForFontMgr 



$400 
$500 
$600 

$700 
$800 
DPForPrintMgr - $900 



var 



toolRec 
paramBlock 



ToolTable; 
FilaRec; 



(begin St art UpTools... J 

(11 pages total direct-page space} 

(offset to QuickDraw direct pages} 

(offset to Event Mgr direct page} 

(offset to Control Mgr direct page) 

{offset to IdneEdit direct page) 

[offset to Menu Mgr direct page} 

{offset to Std. File direct page) 

(offset to Font Mgr direct page) 

(offset to Print Mgr direct pages) 

(Tool Locator record-type) 
(ProDQS 16 parameter block) 
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basenp 



; Integer,* 



label 1; 




Sta rtUptoo 1 a : -TRUE ; 
TJ,StartUp; 
CheckToolError [SI) ; 

my Memory ID : = MMStartOp; 

HTStartOp,- 
CheckToolError ($2) ; 

too 1 sZeroP age : - 

N«wHandl» (TotalDP , 
myMemorylD, 
att r Bank+ att r Fi xed+ 
attrLocked+stt rPag&, 
Ptr<C)>; 

CheckToolError (S3) ; 

baseDP := LoWoBdttoolsZeroPage") ; 
QDStartDp 



(start address of direct pages) 
(label used for disk-mount loop} 



{Start by assuming all will go well} 
(start up Tool Locator) 
{check for error) 

(Start up Memory Manager: it returns 
a User ID for HodgePodge to use) 
(Start up Misc Tools) 
(check for error) 

(The tools need direct-page space:} 

(allocate 11 pages, supplying...} 
{-.Hodgepodge's User ID..) 

[-.these memory-block attributes...) 
[...and make it in bank $00) 
(check for error) 

(get the 2-byte address of the space} 



{BaseDP+DPFo 


cQuickDraw, 


{address of QuickDraw's 3 dir. pages 


SereenMode , 




{ S40 mode} 


MaxScan, 




(max size of scan line} 


myMemorylD) ; 




(Hodgepodge's User ID) 


CheckToolError {$4}; 




(check for error} 


EHStartUp 






(BaseDP+DPForEventMgr , 


(address of Event Mgr's direct page) 


20, 




(event queue size) 


0, 




(X min clamp} 


MaxX, 




(X max clamp} 


0, 




(i min clamp} 


200, 




(Y max clamp} 


myMemorylD) ; 




(HodgePodge" 3 User ID] 


CheckToolError ( $5) ; 




(check for error) 



Next, StartUpTools loads all RAM-based tools and RAM 
patches to ROM-based tools at once, with the LoadTools call. It 
first puts a simple message on the screen to notify the user that it 
is busy; then it constructs the tool table (the list of all tools to 
load); and then it loads them. 



MoveTo(20,20) ; 
S»tBackColor ( ) ; 
BatForaColor(15) 



(Move Pen where we want It] 
(Background color - black) 
(Foreground color = white) 



Step 1 . Start the program 
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Drawstring ( ' One Moment Please .,,'); 
ShowCursor ; 



toolRec. 
toolRec. 
toolRec. 
toolRec ■ 
toolRec . 
toolRec . 
toolRec , 
toolRec . 
toolRec. 
toolRec . 
toolRec . 
toolRec . 
toolRec . 
toolRec . 
toolRec. 
toolRec . 

toolRec. 
toolRec. 
toolRec. 

toolRec. 
toolRec . 
toolRec . 
toolRec . 
toolRec . 
toolRec . 
toolRec . 
toolRec. 
toolRec . 
toolRec. 



numTools 
tools [1] . 
toals[l] . 
tools [2] . 
tool 3 [2] . 
tools [3] , 
tools [3] 
tools [4 j 
tool 9 [4 J 
tools [5] . 
tools [5) 
tools [6 J 
tools[6) 
tools [7 ] 
tools [7 ) 
tools [6] 
tools [8] . 
tools [9] . 
tools [9] . 
tools [10 J 
tools [10) 
tools [11] 
tools [11] 
tools [12] 
tools [12J 
tools [13] 
tools[13] 
tools [14] 

tOOl3[14] 



:= 14; 
tsNum : = 4 ; 
minVersion :- 
tsKum :- 5; 
minVersion : ~ 
tsHum := 6; 
ruin Vera ion :«* 
tsNum :■= 14; 
minVersion := D 
tsNum t- 15; 
minVersion I" 
tsNum := 16; 
minVersion :« 
tsNum := IB; 
minVersion :<• 
tsNum i= 19; 
minVersion := 
tsNum :- 2 0; 
minVersion := 
•tsNum :- 21 
•minVersion 
.tsNum :- 22 
.minVersion 
.tsNum :- 23 
.minVersion : — 
.tsNum :- 27 
. minVersion 
. tsNum := 28 
.minVersion 



paramBlock. pathname := G '* /SYSTEM/TOOLS" 
GET_FILE_INFO (paramBlock) ; 
£f toolErrOO then 

if MountBootDisk = 1 then 

goto 1; 
el Be 
begin 
StartUpTools := FAX5E; 
Exit; 
end; 

LoadTool* (toolRec) ; 
CheckToolError($6) ; 



(Write the atring on screen..) 
(-and display the arrow cursor} 

[Now load RAM based tools 

(and RAM patches to ROM tools) 
— first, define the contents 
of the Tool table : } 

(14 tool sets to be loaded) 
(QuickDraw //} 

[Desk Manager) 

(Event Manager) 

(Window Manager) 

(Menu Manager) 

(Control Manager) 

(QuickDraw Aux) 

(Print Manager} 

(Line Edit) 

(Dialog Manager) 

(Scrap Manager) 

(Standard File) 

[Font Manager) 

[List Manager) 

(Now load the tools we've defined:) 
there's the label) 
f c =pathname of tool directory) 
[Look for that directory:) 
(If it's not there...) 
(Ask user to mount boot disk...) 
(...If OK go back and try again) 
(But if user cancels...) 

(tool startup fails!) 
[„.so quit this subroutine) 

{But if all is OK...} 

{...load the tools nairted in Tool Table} 

(check for error) 
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Note that, if the disk with the needed tools isn't on line, 
Startup! oo Is calls the routine Mount BootDisk, which 
prompts the user to remount the boot disk so tool loading can 
continue. MountBootDisk is described under "Error Handling" 
in Appendix D. 

Once all the tool sets have been loaded, they need to be started 
up. StartUpTools now starts each one, in the proper order and 
with the proper input parameters as needed. 









WindStartOp (fnyMemoxylD) ; 
CheckToolError (S7) ; 

Raf rftahEaaktop (NIL) ; 

CtlStaxtOp 

[rrsyMemorylD, 
BaseDP+DPForCtlMgr) ; 
CheckToolError (58); 

LE Start Qp 

(BaseDP+DPForLineEdit ,. 
myMemorylD) ; 
CheckToolError ($9) ; 

Dla logs tart Up 

(rm/MemorylD) ; 
CheckToolError ( $A) ; 

MenuStartUp 

[myMamorylD, 
BaseDP+DPForMenuMgr) ; 
CheckToolError (SB) ; 

D*»kSta£tUp; 
CheckToolErmr ($C) ; 

ShowP 1 ea s eWait ; 

SFStartDp 

(myMemorylD, 

BaseDP+DPForStdFile) ; 
CheckToolError ($D) ; 
SFAllCapa (TRUE) ; 



QDAuxStartUp; 
CheckToolError ($E> ; 



( start up Window Manager) 
(check for error) 

(redraw desktop) 

( start up Control Manager) 
(Dser ID for memory blocks ) 
(address of Ctl Mgr's direct page) 
(cheek for error) 

(start up Line Edit} 
{address of LineEdit ' s direct page) 
(User ID for memory blocks} 
(check for error} 

(start up Dialog Manager} 
(User ID for memory blocks } 
{ check for error) 

(start Up Menu Manager) 
{User ID for memory blocks] 
[address of Menu Mgr's direct page) 
{check for error) 

{start up Desk Manager) 
{check for error) 

{Bring up a dialog box that says 
"Please wait while we..," ) 

(start up Standard File) 

| User ID for memory blocks} 

{address of Std File's direct page) 

[check for error) 

{Display file names in all caps] 

(start up QuickDraw Aux] 
{check for error) 



Step 1 , Start (be program 
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WaltCursor; 

FMStartttp 

(jnyMeircrylD, 

BaseDE+DPForFontMgr} ; 
CheckToolError ($F) ; 

IilotStartDp; 
CheekToolError (S10) ; 

SerapStartrjp; 
CheckToolError ( SI 1 ) ; 

PHStartUp 

(n^MeiroryXD, 

BaseDP+DPForPrintMgr) ; 

CheckToolError ($12) ; 

HidePleaseWait; 
InitCursor,- 



end; 



(put up watch cursor, 
now that it's available) 
{start up Font Manager) 
(User ID for memory blocks) 
(address of Font Mgr'a direct page) 
(check for error) 

(start up List Manager) 
(check for error) 

(start up Scrap Manager) 
(check for error) 

[start up Print Manager) 
(OserlD for memory blocks) 
(address of Print Mgr'g 2 dir. pages) 
(check for error) 

(Remove the "Please wait...") 
[restore normal cursor) 

(End of StartUpTools) 



ShowPieaseWoit and 

HldePleaseWalt ore described 
under "Constructing Diafog Boxes 
and Alerts' | n Chapter d. 



This completes toolbox initialization. The routine StartUpTools 
ends and returns control to the main program which, in addition 
to calling the two short initialization subroutines Setup Windows 
and SetUpDe fault (described earlier in this section) calls the 
subroutine that sets up the menu bar. That routine, SetupHenus 
is described next. 

* SbowPleaseWaiL During tool startup, the HodgePodgc routine 
Showpieaaewait is called, It puts up a dialog box that informs 
the user that the startup process may take a few seconds Wheu 
startup is done, HidePleaseWait removes the dialog box from 
the screen, Keeping the user informed is an important 
component of the Human Interface Guidelines. 

♦ Emr handling: You may have noted that, after each tool 
startup call, the HodgePodgc subroutine CheckToolError is 
called. CheckToolError is a very simple error handling 
routine; it is described under "Error Handling" in Appendix D. 
It is good practice to routinely check Tor errors after making 
tool calls that can return them. 
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- Sri I UpMur'iuS 



M 






Satiipf'j'RnLJS is In L hs spurge file 
M.=NU.=AS. 



Set up the system menu bar 

Hie lou Line that, sets up the menu ha r when l lodge L'odge .slarls up 
is called Set upMenus. ^etupMenuJ is called from [he main 
program, after StartUpTooIs and |ho Lwo small iniliali nation 
routines. 

For each menu in turn. SetupMenus calls the Menu Manager 
routine NewMenu, passing it a pointer to a set of diaraerxir strings 
l.hal. dcifine die menu name and ihe items it contains. (The menu 
strings were defined in the routine iniL-Globals .') New.Menu 
returns a handle to the newly c.n-.'Alv.d menu. SetupMer. us then 
calls lnsertMenu, passing it the menu handle and :i position 
paramd^r (here defaulted to zero.), to put the menu into ihe menu 
har. 

Finally, !?er.UpMe]iuLJ adds ail desk accessory names lo the AppU: 
menu Cwkh fne DeslcMarsagtir call FixApplemenu), calculates the 
height of the menu bar, and draws the bar. 



va J" heigjit;! T nteger ; 

SafcMTitleStart (10}; 

InsartMenu (New Menu (@ i'oriL UenuS L f [ 1 ] ) , ) ; 
InaartMenu (NewHenQ (tWi:nJ.-jwM<SiiuSt 1 HI } , C) . 
IneertM&im (NowMonu (SEditMonuSt?: f1 1 ) , A) ; 
InsertMonu (NawManu {QFilcMfciuiStr f 1 1 ) , 0) ; 
InsertMtanu (NfiwMftnu (@ApplcMt>rniSr.r f] ] j ,&>•/ 

FiKApplaM&nu ( Anp 1 eMe nn I D ) ; 



{begin SetupMen^s...) 

{- height oi <m?nu £lulL) 



(Set yty^'L position, from Left edge 
ofc menu hii, of first worm r.itle} 
{ create r-nd in serf: Fnnts Menu) 
{create snrl insert Windows Menu} 
{create and insert Edit Menu) 
(srest-.e And insert File Men^) 
{crestft and insert Apple Menu} 

{Aid DAs to apple menu} 



height :- FixMenuBar; 
D r a wKenuD a r ; 



end; 



{Get sizes of menus J 

{ . . . a.'.y! firaw L\v± iN&tWL iJiir - ) 

{End of SetU^tlenua) 



Step 1 . Start the program 
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MainEvent 



TaskMaster and GetNexfEvent 
are further described under 
'Handling Events" in Chapter 3. 






Step 2. Cycle through the main event loop 

A desktop application spends most of its time in the main event 
loop, wailing for an event to handle. How an application functions 
is determined by what events it chooses to handle and how it 
handles them. The event loops for most programs are quite 
similar — it is in the subroutines to which the various events cause 
branches that the special personality of each application lies. 

HodgePodge's main event loop is diagrammed in Figure 2-5. 
Each time through the loop, HodgePodge checks whether it's lime 
to quit. If it isn't, HodgePodge adjusts menu items if necessary 
and then looks for the next event. It does this by calling the 
Window Manager routine Taskmaster. Alternatively, an 
application could call the Event manager routine GeiNextEvent. 

HodgePodge uses TaskMaster because TaskMaster automatically 
handles many events for it, TaskMaster itself calls GetNexlEvent, 
and takes care of events that affect the size and shape of windows, 
such as a mouse click in the Zoom, Close, or Grow boxes. This is 
not a requirement; your application can ignore TaskMaster 
entirely and do all event- handling itself. For example, you might 
not use TaskMaster if you want the application to respond in an 
atypical manner. 

If TaskMaster can't completely handle an event, it passes a task 
code (described in "Handling Events" in Chapter 3) back to the 
application, and the application must deal with the event 
specified by that code. For example, if the user selects a menu 
item, TaskMaster passes the information back to the application, 
which must find out which item was selected and take the 
appropriate action. 

When action on an individual event is finished, the application 
Cor TaskMaster) returns to the main event loop to wait for the next 
event. 
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back to 
main program 



DoMenu 



* DoCloseltem 



Figure 2-5 

Hodgepodge's main event loop 



MolnEvent is In the source file 
EVENT. PAS, 



The loop 

Here is the code for Hodgepodge's main event loop. Compare it 
with Figure 2-5. Depending on its features, your application may 
have an identical event loop, or it may respond to a different set 
of events. 



Step 2. Cycle through the main event loop 
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procedure MainEvent; 
var code : Integer; 

beg£a 

Event. wniTaskHask := S00001FFF; 
done :- FALSE; 

repeat 

CheckFrontW; 

code :- TaaXMaster ($FFFF, Event) 



case code of 
wlnGoAway: 

DoCloseltem; 
wlnSpecial , 
wlnMenuBar : 
DoMenu 
end; 



until done; 



end; 



(begin MainEvent...) 

{the task code (or event code} 

returned by TaskMaster) 

(pass all events to TaskMaster) 

(initialize the Quit flag! 



(adjust menu items if necessary) 
(Call TaskMaster: let it handle 

all events; record name=Event; it 

returns the task code) 
( If the task code represents...) 
(If a window close box selected...} 
(...go to DoCloseltem) 
(If an Edit-roenu item or a...] 
(...regular menu item selected^) 
(...go to DoMenu) 
{end of Case statement) 

{Stop when Done=TRUE) 
{End of MainEvent} 



The different events are specified by toolbox-defined constants 
(such as winMenuBar) that define Event Manager and TaskMaster 
event codes. See Chapter 5. 

The main event loop here is much shorter than it would be if 
TaskMaster were not used. Without TaskMaster, there might ] 
been as many as 16 separate items in the above case SLatement, 
each with its own subroutine call. 

♦ Check front window: Each time through the loop, before 
checking for events, HodgePodge determines which window ( 
any) is the Frontmost, and adjusts menu items accordingly. 
example, if the front window is a font window, the Save item c 
the File menu should be disabled because HodgePodge dc 
not save font-window contents to disk. If the front window is i 
desk accessory window, the Edit menu should be enabled. 

The routine that does this menu manipulation is CheckFront 
It is in the source file event . PAS. See Appendix G, 
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Step 3. Handle specific events 

II may already seem that the organisation of this program is a 
liule different from what you expected. So far, we've seen no 
major divisions of the code into "Picture Window Stuff and 
"Font Window Stuff," as you might expect in a program whose 
principal tasks are the manipulation of picture windows and font 
windows. 

Event-driven programs have the equivalents lo such modules, but 
they are chopped up and arranged in different ways. Elements of 
them are distributed throughout the flow of events in the program 

Therefore let's continue along the path of execution, seeing where 
we go when we leave the main event loop to handle the events 
that Hodgepodge responds to. We'll mention each of the types of 
events and point you to where in the book to look for the specific 
routine Lhat handles that event type. 



Window closing Is described 
under "Window-Related Events/ 
later In this seclt on, 



Window-content definition 
procedures ate discussed 

under 'Oeotlng Windows' 
Chapter 4. 



In 



TaskMaster-handled events 

In Hodgepodge, TaskMaster automatically handles all moving, 
resizing, scrolling, activating, updating, and redrawing of windows. 
It handles nearly all window events automatically. This is a great 
convenience (as you can imagine if you are a Macintosh 
programmer) and it means that, apart from dosing a window, 
there is little for HodgePodge lo do in terms of window 
manipulation. 

In general, there is one thing that TaskMaster cannot do for an 
application, and that is draw the contents of a window. TaskMaster 
cannot know what purpose the application created the window for. 
But, if a window's contents can always be described by a routine, 
an application can provide TaskMaster with a way to call that 
routine whenever a window is drawn. That routine, although part 
of your program, acts as a sort of extension to TaskMaster, and it 
can do the redrawing of the window's contents. Such routines are 
called window- con lent definition procedures. 

HodgePodge uses this trick for both picture windows and font 
windows. Figure 2-6 is an extension to part of the event-loop 
diagram of Figure 2-5, and shows the window-drawing routines that 
are called from within TaskMaster. 
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no / Any \ 
■ — ■-, event ■■ 
\ ? / 

I 



TaskMaster j— 



Pairv 



^ DlspFontWJndow 



Figure 2-6 

HodgePodge routines called by TaskMaster 

# JVWe: Don't get the impression from Figure 2-6 that drawing 
window contents is all [hat TaskMaster does, TaskMaster i 
many more things, as already discussed, but Paint and 
DispFont Window are the only HodgePodge routines that 
TaskMaster calls. 



Paint Is In the source file 
PAINT-PAS. 



Picture window contents 

When a picture window's contents need to be drawn or redraw 
TaskMaster calls the definition procedure Paint, which sets up 
the proper parameters and then calls the routine Paintit to i 
the actual drawing. Paint It is described under "Drawing to ! 
Screen (and elsewhere)" in Chapter 3. Paint looks like this: 



procedure Paint; 

var tmpPort : GrafPortPtr; 

myDataHandle: WindDataH; 

.begin 

tmpPort t- GotPort; 

myDataHandle ;- WindDataH( 

GatWRafCon (tmpPort) ) ; 

Paint It (myDataHandle^.pict) ; 

and,' 



(begin Paint...} 

(painter to a. grafPart) 
(handle to a window-data record 
—defined in GLOBALS.PASI 

(get a pointer to current port} 
(Get a handle to the window-data...) 
{,.. record for the current port) 
(Using the picture pointer in the...) 
(,., record, call the routine that 
draws picture -window contents} 
(end of Paint} 
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Note that Paint (andPaintlt 100, as you will see) is completely 
unconcerned about where on the screen the window to be drawn 
appears, what other windows may or may not be in front of it, and 
even how big the window is or what part of the picture is being 
displayed. All these details are taken care of by the toolbox! 



DlipFontWindow Is In the source 

file FONT. PAS. 



Font window contents 

When a font window's contents need to be drawn or redrawn, 
TaskMaster calls the definition procedure DispFontWindow, 
which sets up the proper parameters and then calls the routine 
ShowFont to do the actual drawing. ShowFont is described in 
Chapter 3, under "Drawing to the Screen," DispFontWindow 
looks like this: 



procedure DispFontWindow; 

var tirjiPort : GrafPortPtr; 

myDataHandle : WindDataH; 

begin 

trrpPort :- GstPort; 

myDataHandle :- WindDataH! 

G*tWR*fCon (tmpPort ) ) ; 

with myDataHandle"" do 
ShowFont (theFont, isMono} ; 



end/ 



{begin DispFontWindow...} 

(pointer to a Graf Port) 
(handle to a window-data record 
—defined in GLOBALS.PAS} 

(Get pointer to current port] 

(Get a handle to the window-data..,} 

(...record for the current port) 

(Using font info from the record.,.} 
(...call the routine that draws 

font-window contents} 
(End of DispFontWindow} 



Just as in the case of picture windows, DispFontWindow and 
ShowFont are completely unconcerned about where on the 
screen the window to be drawn appears, what other windows may 

or may not be in front of it, and even how big the window is or 
what part of the font display is to be drawn. The toolbox does it 
all. 



Step 3. Handle specific events 



53 



Menu-related events 



DoMenu is In the source file 
MBNU.PAS, 



Each of the subroutines listed in this section is called as the re 
of a menu selection made by the user. Thus there is one 
subheading for each HodgePodge menu entry. Figure 2-7 is in 
extension to part of Figure 2-5; it shows which routines can be 
called when the main event loop sends a menu-related event [ 
the routine DoMenu. 

When a menu item is selected (either with the mouse or with : 
keyboard-equivalent), TaskMasier returns 17 ( = winMenu Bar- 
see "Handling Events™ in Chapter 3) as the value of my Event, 
which causes execution to pass to the subroutine DoMenu. 
TaskMaster also sets the taskData field of the extended task 
event record equal to the menu ID and the ID of the item 
selected, and then passes control back to HodgePodge so it : 
perform the specific task. DoMenu looks like this: 



procedure DoMenu; 



(begin DoMenu...) 



var menuNum: 

itemtftim: 



Integer; 
Integer; 



begin 

menuNum :- H±Word (Event .wmTaskData} 
itemNum := LoWord (Event .wmTaskData} . 



case itemNum of 

About Item: 

Openltem: 

Closeltem; 

SaveAsItem: 

ChoosePItem: 

PageSetltem: 

Print Item: 

Quitltem: 

Dndoltem: 

Cut It em: 

Copyltem: 

Pasteltem: 

Clearltem; 

Font Item; 

Monoltem: 
ot Jiarwi se 

DoWindow (itemNuni) 
end; 



DoAboutltem; 
DoOpenltem; 
DoCloseltem; 
DoSaveltem, 1 

DoChooserltem; 
DoSetupItem; 
DoPrintltem; 
DoQuitltem; 



DoOpenltem; 
DoSetMono; 



Hilit«M«nu (FALSE, menuNum) ; 



end,* 
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(get number of menu and item J 



(bring up "About HodgePodge" dialog} 

(open a picture window} 

(close a window} 

(save a picture file} 

(choose a printer) 

(do page-setup} 

(print contents of a window} 

(quit HodgePodge) 



(ignore special menu items) 

(open a font window} 
{ set font spacing} 

{bring the chosen window to front) 
{of Case statement} 

[unHighlight menu title) 

{End of DoMenu) 
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The menu ID variables (Close Item, About Item, and so forth) 
arc defined in the source file GLOBALS . PAS, 



'Menu\ V m 

event / * 
'■-. ? .-■''" 

(no 



DoMenu 



DoSaveltem 



-i DoChooseltem 



DoWlnctow 



DoClcseltem 



DoAboutltem 



DoQultltem 



DoOpenltem 



DoSetupltem 



DoPrlntlrem 



L DoSetMono 



Figure 2-7 

HodgePodge routines that handle menu-related events 

The various routines called by DoMenu are listed either elsewhere 
in this book or in Appendix G. In brief, this is what each does: 

■ DoAboutltem: Brings up the "About HodgePodge" dialog box. 
DoAboutltem is listed under "Constructing Dialog Boxes and 
Alerts" in Chapter 4. 

■ DoOpenltem; Opens a font or picture window, DoOpenltem 
calls Openwindow to open the window, then calls AddToMenu 
to add the window's name to the Windows menu. DoOpenltem 
is listed under "Opening a Window: An Example" in Chapter 4, 
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■ Docloseltem; Closes a font or picture window, releases its 
allocated memory, and adjusts the Windows menu. 
DoCloseltem is listed under "Window-Re i a ted Events " Jat 
in this section. 

■ DoSa^eTtem: Saves the contents of a picture window as a diskl 
We. Do Save It em is listed under "Communicating With Files 
and Devices" in Chapter 5. 

■ DoChooserltem: Brings up a dialog box permitting the user | 
choose a printing device. DoChooserltem is listed under 

Communicating With Files and Devices" in Chapter 5. 

■ DoSetupItem: Brings up a dialog box permitting the user to i 
page-setup parameters, DoSetupItem is listed under 
"Communicating With Files and Devices" in Chapter 5. 

■ DoPrtatltem; Prints the contents of the frontmost window 
DoPnntltem is listed under -Communicating With Files an<! 
Devices" in Chapter 5. 

■ DoQultltem; Assigns the value TRUE to the boolean variable 
done. That causes temination of the main event loop 
DoQuitltero is in the source file MENU . PAS. See Appendix 

■ DoSetMono: Toggles a flag that controls whether fonts are 
displayed as monospaced or proportional, and updates the 
Fonts menu accordingly. DoSetMono is in the source file 
FONT. PAS. See Appendix G. 

1 w,°T indOW: Brin8S the selecIed window Chosen from the 
Wmdows menu) 10 the front. DoWindow is in the source file 
MENU. PAS See Appendix G. 



Window-related events 

Closing is Lhe only window-related event that HodgePodge muse 
respond to explicitly. Figure 2-8 ,s an extension to part oF Figure 
2-5; it shows the routines that can be called when the main event 
loop encounters a window-related event. 
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■■ Close"'., yss 

window '■; 

-, event / 
'■-,. ? / 



I no 



-J DoCloseltem 



1_ 



AdjWind 



Figure 2-8 

HodgePodge routines that handle window- related events 



DoCloseltem Is In the source file 
WIN DOW. PAS. 



Closing is a window event, but ii is also a menu event . When the 
user clicks in an active window's close box, or selects Close from 
the File menu, Taskmaster returns that information to 
HodgePodge, which in turn calls DoCloseltem, DoCloseltem is 
also called at program shutdown, to close all windows. Its source 
code looks like this: 



procedure DoCloseltem; 

var theWindow : GrafPortFtr; 
myDataHandle : WindDataH ; 

begin 

theWindow : ■= FrontWindow; 

Clo*»NDAbyWinPtr (theWindow) ; 

if isToolError tb&n 
b&gin 
AdjWind (theWindow) ; 
nyDataHandle ;- WindDataH ( 

GatWRafCon (theWindow) ) 
DiopoaoHandls (Handle (myDataHandle) ) ; 
Clo»«Hindow( theWindow) ; 
Dec (w Index) ; 
end; 
end; 



(begin DoCloaeltein...} 

(ptr to window to be closed) 

[window-data-record handle) 



(Get a pointer to the front window} 

(Assume that it ' a a desk ace. window) 

(If it wasn't an NDA window...) 

[Call AdjWind to update menu) 
[Get a handle to window's...) 
{...window-data record) 
(Get rid of the window-data record) 
(Get rid of the window completely) 
(decrease number of open windows) 
(end of IF wasn't an NDA) 
(end of DoCloseltem) 



*> AdjWind- DoCloseltem calls the HodgePodge routine 
AdjWind, which removes the name of the just-closed window 
from the Windows menu. AdjWind is described under "Making 
and Modifying Menus" in Chapter 5. 
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_ ShutDownTools 



ShutDownTools Is In the source tile 
HP.PAS. 



procedure ShutDownToola, 1 
-begin 

D«*k Shut Down; 

if WindStatuo <> then 
H ideAl lWindow s ; 

List Shut D own f 
FMShntDown ; 
S crap Shut Down ; 
PMShutDown; 
QDAux Shut Down ; 
SFShutDown; 
M»nu Shut Down ; 
D ialogShutDown ; 
LEShUtPown; 
Ct IS hut Down; 
WindShutDown; 
EHShutDown; 
QDShutDown; 
MTShutDown; 



Step 4. Shut down the program 

When it's time for your application to quit, the following steps 

ensure a graceful exit: 

}. Shut down all tool sets in reverse order from the way you 

started them up. 
Z Release any memory your application requested from the 

Memory Manager, 

3. Shut down the Memory Manager (with your application's L'ser 
ID as input). 

4. Shut down the Tool Locator. 

5. In assembly language, use the ProDOS 16 QUIT call to leave Uk 
application. On C and Pascal, this is taken care of for you). 

HodgePodge terminates when the user selects Quit from the File 
menu. The routine DoQui tit em executes, setting the variable dons 

to TRUE, which causes the main event loop to stop. Execution pissa 
to the main program, which calls ShutDownTools and ends. 

ShutDownTools shuts down all tool sets, in reverse order from 
startup. You may be able to use this code verbatim in your 
programs, It looks like this: 

(begin ShutDownTools...} 

(shut down Desk Manager} 
(make sure Window Mgr. active..} 
(close all windows — this may tales 
some time if many open windows! } 
(shut down List Manager} 
(shut down Font Manager} 
{shut down Scrap Manager} 
{shut down Print Manager} 
< shut down Quick Draw Aux) 
{shut down Standard File} 
( shut down Menu Manager } 
(shut down Dialog Manager) 
( shut down Line Edit } 
(shut down Control Manager} 
( shut down Window Manager} 
(shut down Event Manager} 
{shut down QuickDraw II} 
(shut down Misc. Tool Set} 
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<> then 



if MMStatu* 
begin 
DI»po*«Sandla [toolaZeroPage) 
HMShutDown (myMeinoirylD) ; 
end; 
TLSbutDown; 
ead; 



tlf Memory Mgr- active..} 
(delete the direct -page memory..,} 
(...allocated at startup) 

(shut down Memory Manager} 

(shut down Tool Locator} 

(End of ShutDownTools} 



* HideAUWindows: Note that ShutDownTools calls 

HideAUWindows, which simply closes all windows and 
releases their associated memory. HideAUWindows is in the 
source file WINDOW. PAS. See Appendix G. 



Conclusion 

This completes our overview of the organization of Hodgepodge. 
You can see that it has a structure almost independent of the tasks 
it was written 10 perform. That, of course, is the intention— if all 
event-driven programs execute in a similar manner, they can 
present a uniform interface to the user. In addition, they can be 
extended easily to add new features, and they can remain 
compatible with future revisions of system software. 

The rest of the book gives more details on how Hodgepodge 
actually performs its individual tasks, and gives some of the 
concepts behind the tool calls that HodgePodge, like any event- 
driven program, needs to make, Most discussions are general, but 
HodgePodge listings arc included where appropriate. See Table 2-1 



Table 2-1 
HodgePodge routines 



described In this book 



Routine 



See chapter and section... 



AddToMenu 

Adjwind 

AskUser 

CheckToolError 

CheckDiskErrOr 

Di spFontWindow 

DoAboutltem 



Chap. 5: "Making and Modifying Menus" 

Chap. 5: "Making and Modifying Menus" 

Chap. 5: "Communicating With Files..." 

App. D: 'Error Handling" 

App. D: "Error handling" 

Chap. 2: "Handle Specific Events" 

Chap. 4: "Constructing Dialog Boxes..." 



Conclusion 5° 



Tabfe 2- 1 (continued) 

Hodgepodge routines described in this book 




Routine 



See chapter and section,.. 



DoChooseFant 

DoChooserltem 

DoCloseltem 

DoMenu 

DoPrintltem 

DoSaveitem 

Do Setup I tern 

Do The open 

DrawTopWindow 

HodgePodge 

InitGlobals 

StartUptools 

LoadOne 

MainEventLoop 

MountBootDisk 

OpenWindow 

Paint 

Paintlt 

SaveOne 

SetUpDefault 

SetUpMenus 

SetUpWindows 

ShowFont 

ShutDownToola 



Chap. 3: "Drawing to the Screen" 
Chap. 5: "Communicating With Files 
Chap. 2: "Handle Specific Events" 
Chap. 2: "Handle Specific Events" 
Chap. 5; 'Communicating With Files 
Chap. 5: "Communicating With Files... 
Chap. 5; "Communicating With Files.,.' 
Chap. 4: "Creating Windows" 
Chap. 5: "Communicating With Files.,." 
Chap. 2: "HodgePodge at a Glance' 
Chap. 2: "Start the Program" 
Chap, 2: "Start the Program" 
Chap. 6: "The ProDOS File System" 
Chap. 2: "Cycle Through the MainEvcni" 
App. D; "Error Handling" 
Chap. 4: "Creating Windows" 
Chap. 2: "Handle Specific Events" 
Chap 3: "Drawing to the Screen" 
Chap, 6: "The ProDOS File System" 
Chap. 2: "Start the Program" 
Chap. 2: "Start the Program" 
Chap. 2: "Start the Program" 
Chap, 3: "Drawing to the Screen" 
Chap. 2: "Shut Down the Program" 
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Chapter 3 



Using the Toolbox (I) 
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The complete reference for oil 
toolbox colls Is the Apple ugs 
Toolbox Reference, In two 
volumes. 



In Chapter 2, the sample program HodgePodge showed an 
example of toolbox use in action. Now let's examine some of the 
concepts behind the loolbox calls HodgePodge makes. Even 
though an introductory book like this can only get you started 
each too] set, the overall view of what the tools can do for you 
and the example of how 1 lodge Podge integrates them should tit 
you a long way toward understanding and exploiting their power. 
The App!e IIGS Toolbox is made up of about 30 tool sets Each 
tool set lS made up of many routine,. In all, there are more thar, 
800 toolbox routines in ROM and RAM, covering a wide variety J 
tasks from managmg memory to drawing to the screen to g ivnm 
you the time of day. And don't worry-j^ needn't memorize 
Ibemall to write an Apple IIGS application. Just the few yn u learn 
from this book will get you started. 

You can think of the toolbox as a very large library of prewritj 
subrout.nes, opumized and integrated to relieve you of a large 
part of your programming burden. They exist to free you to 
concentrate on the fundamental, creative aspects of the progrj J 
you want to write. y s 

In ihis chapter we discuss events and how to handle them, and I 
basic process of drawing to the Apple Ugs screen by using 
QuickDraw II. Chapters 4 and 5 descr.be the remaining tool se[s 
Well include actual examples from HodgePodge where 
appropriate, but otherwise the details of individual calls and their 
parameters are left for other books. 



Starting up and calling the tools 

ItfSt mUSt ^ b0th l ° aded 3nd SlaHed "P W™ V™ can call 

start Im" rOUt T A1S °" S ° me t0 ° J SCtS CaM oth ^ » V* H 
start mem up m the proper order. 



Required tool sets 

IpTe UGS Tonth™ 1 T T^ ** "* *&»** using the 
Apple IIGS Toolbox. Start them first, and start ihem in this order; 

1. The Tool Locator 
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I 



Itefsr to "Set the Stage" in 
Chapter 2 to see how closely 
HodgePodge follows this 
sequence. 



Hodgepodge's tool table Is 

Initialized in the routine 
StartUpTooSs. 

Important 

Fo! a list of all current tool sets and 
tneir numbQrs, see "User Tool 
Sets" In Chapter 8. 



2 The Memory Manager 

3. The Miscellaneous Tool Set 

Beyond these three, there are two other tool sets that, while not 
absolutely required for the Apple OGS to function, are nevertheless 
used in nearly every application, Stan ihem up in this order: 

4. QuickDraw II 

5. The Event Manager 



Other tool sets 

After the required tool sets are in place, you should load and start 
up all other tool sets your application might use. 



Loading 

To simplify things, and to ensure that the correct versions of tool 
sets are available, it's best to load all of your needed tool sets at 
once, with the Tool Locator's LoadTools call. LoadTools does two 
things: it loads RAM-based tools into the computer (remember, 
some tools are not in ROM), and it checks the version numbers of 
all the specified tool sets, whether in ROM or RAM. That version 
check is important because some tool sets will not function 
without the proper minimum versions of other tool sets. 

When you make the LoadTools call, you pass it a pointer to a tool 
table, which lists the total number of tool sets to load, and the 
number and minimum acceptable version of each tool set. 



Make sure that all the RAM-based tools your program needs are In 
the TOOLS subdirectory of the SYSTEM directory on the system disk. 
See Appendix C, 



Starting up 

After you have loaded the remaining tool sets, you must then start 
up each one. Each tool set has its own startup call; some calls 
require or return parameters, others have no inputs or outputs. 
Because some tool sets require the presence of other tool sets in 
order to function, tool sets must be started in proper order. Table 
3-1 gives the suggested startup order. 



Starting up and calling the tools 
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Table 


3-1 




Tool set startup order 


Hex. 


Dec. 


Name 


$01 


1 


Tool Locator 


$02 


I 


Memory Manager 


$03 


5 


Miscellaneous Tool Set 


$04 


4 


QuickDraw II 


$06 


6 


Event Manager 


50E 


14 


Window Manager 


$10 


16 


Control Manager 


$0F 


15 


Menu Manager 


314 


20 


LineEdit Tool Set 


$15 


21 


Dialog Manager 


$05 


5 


Desk Manager 


$17 


23 


Standard File Operations Tool Set 


$16 


22 


Scrap Manager 


$1C 


28 


List Manager 


$13 


19 


Print Manager 


$1B 


27 


Font Manager 



You can assume that tool sets not on this list are either started 
already, or can be started in any order. 

■> HodgaPadge: You may have noticed that HodgePodgc doesn't 
follow this sequence exactly when it starts its tool sets. 
Specifically, it starts up the Menu Manager after starting the I 
LineEdit Tool Set and the Dialog Manager. So in some 
instances it may be possible to alter startup order slightly, 
is safest just to follow the order given in Table 3-1. 

In addition to the dependencies reflected in the startup order 1 
tool sets, there are additional, complex dependencies among tool 
sets because a routine in one tool set may caU routines in othjT 
tool seLs (which mav call routines in still other tool sets, and so 
on). These dependencies are beyond the scope of this book; sfl 
the individual tool set and routine descriptions in the Apple Ili 
Toolbox Reference, 
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Calling an individual routine 

You can access toolbox routines easily from either assembly 
language or high-level languages. The initial languages offered 
with the Apple IIGS Programmer's Workshop (APW r described in 
Chapter 7) are 658 16 assembly language and C; macro libraries 
and interface libraries are available for these languages. Any other 
languages with similar interface libraries (such as the TML Pascal 
used to write the Pascal version of Hodgepodge) allow similar 
tool-calling procedures. 



The Tool Locator is documented 
fully undQi "Trie Too! Locator in 
ttie Apple IIgs Toolbox 
Geferenca 



The Tool Locator 

Every time you make a tool call, your request goes mrough the 
Tool Locator, the first tool set started up at the beginning of your 
program. The Tool Locator (in ROM) keeps tables in RAM that 
point to the individual routines (which may be in either ROM or 
RAM). The pointer tables are kept in RAM so that they may be 
easily modified when tool sets are updated, moved to ROM from 
RAM, or otherwise changed. Your application needn't know or 
care where a routine is — it just tells the Tool Locator to get it. 



The Input and output parameters 
lor each assembly-language tool 
call ore described In the Apple 
tIGS Toolbox Reference 



Calling from assembly language 

The simplest way Lo make tool calls from assembly language is to 
use macros. The macros provided with APW relieve you of having 
to remember the tool set number and routine number for each 
call. Assembly-language IlodgePodgc makes all its calls with 
macros. 

Make a tool call as follows: 

1. If the function has any output, push the correct amount of 
space for it on the stack, 

2. If the function has any inputs, push them on the stack in the 
specified order. 

3. Invoke the appropriate macro by name. A macro name is the 
same as the routine it calls, except that, by convention, it has a 
leading underline character. 

4 Check for errors, as described under "Machine State on Return 
from the Call," later in this section. 

5. Pull the output, if any, from the stack. 
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The names of the parameters for 

each fool routing In the C 
language are described in the 
Apple HGS Toolbox Reference. 



You can maker an assembly -language tool call without macros, m 
course. The method is almost identical to that just described, 
except that instead of calling the routine by name, you jump tofl 
the Tool Locator's entry point (St: 1 0000) with a JSL instructio jM 
with the tool set number and routine number as the high- order 
and low-order bytes in the X register. All tool set and routine 
numbers are documented in the Apple lies Toolbox Reference. 
Nevertheless, it is probably best to use macros because names M 
easier to remember and read, 



Calling from a high-level language 

The interface libraries that allow C programmers to access 
Apple IIGS Toolbox are included in APW C. Those libraries 
contain the function definitions for the tools. The steps to call ( 
routine are as follows. Other high-level languages will have ; 
libraries, appropriate to the languages' structures. 

1, Make the routine accessible by using an # include stall 
that includes the appropriate Tile (for example, QuickDraw 
for QuickDraw II calls). The included file will provide the 
function declarations and the necessary constants and data 
structures. 

2, Invoke the call by entering its name and supplying the corn 
parameters, 

3, Examine the global error variable (_toolErr in C, 
ToolErrorNum in Pascal) for errors, if necessary. If the 
variable is equal to zero, no errors occurred; otherwise, it 
contains the number of the error. 



For a complete description of 
register and flag states after o 
toolbox call, see 'Using the 
Apple IIGS Tool Sets" In the Apple 
IIGS Toolbox Reference 



Machine state on return from the call 

When it completes a call, a toolbox routine returns control 
directly to the application that called it. The accumulator com 
zero and the c flag (carry bit) is cleared to zero if the call was 
completed successfully. Other flags and registers have values 
dependent on the specific routine called. 

If an error occurred during the call, the carry bit is set (-1) 
the accumulator contains an error code in this format; 



high-order byte 
low-order byte ■ 



■ tool set number 
error number 
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All toolbox etior codes ate 
summaitzed in an appendix to 

Volume II of the Apple l&s 
Toolbox Reference. 



♦ Error passing: With this method, an error can be properly 
identified even if it occurs during a call to one tool set, but 
doesn't actually show up until a call returns from another tool 
set. For example, using this method, a QuickDraw II call can 
pass on an error message from the Memory Manager. 



Handling events 

The central part of any event-driven program is its main event 
loop. As Figure 2-5 shows in the case of HodgePodge, the program 
continually cycles through the event loop, waiting for an event to 
act upon. The application decides what to do from moment to 
moment by looking at each event and responding to it 
appropriately, 

What constitutes an event? An event is a notification to the 
program that something has occurred, something that the 
program may wish to respond to. It may be a signal from outside 
the program, such as a keystroke. Or it may be something internal, 
such as the need to redraw part of a window when an overlapping 
window has been moved. 

♦ Interrupts: An event is different from an Interrupt in that it is 
generated in software, and that it does not force action by the 
application. An application can ignore any event it does not 
need to act upon. 

The Event Manager is the Apple IIGS tool set that notes these 
occurrences and records them as events (by creating event 
records). For example, whenever the user presses or releases the 
mouse button, the Event Manager records the action in an event 
record. The Event Manager collects events from a variety of 
sources and reports them to the application on demand, one at a 
time. The Event Manager doesn't necessarily report the events in 
the exact order they occur, because some have higher priority 
than others. 

The Event Manager is also used by other parts of the toolbox. For 
instance, when HodgePodge calls TaskMastcr in its main event 
loop, TaskM aster in turn calls the Event Manager. See "Using 
TaskMastcr," later in this section. 
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The event queue 

Most events are placed in an event queue, which is an ordered list 
of event records, As events occur, they are placed at one end of j 
the queue; as the application cycles through its event loop, it pull 
events off the other end, one at a time, by making a call such as 
GclNexlEvent. 

♦ TaskMaster: Rather than call GeLNextEvenc directly, wc suggest 
that your application call Taskmaster instead. The end result, 
however is the same — Taskmaster calls GetNextEvent, which 
pulls events off the event queue as usual. See "Using 
TaskMaster," later in this section. 

Figure 3-1 shows a simplified view of how events are presented to 
an application. All event types, except switch events and the 
window- related events activate and update, pass through the event 
queue. The various types of events are ordered by priority befc-ief 
the application sees Lhem. Also, the application can filter out, or 
mask, types of events that don't apply to a particular situation. 



Application- b 

defined 
events 



Desk 

accesory 

events 



Device 

driver 

events 

Keyboard 
events 

Mouse 
events 




The 
next evert 



Event 
record 



Window Manager events 
(activate, update) 

Switch events 



Figure 3-1 

Events and the event queue 
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Event types 

Events are of various types. Some report, actions by the user; 
others are generated by the Window Manager, device drivers, or 
Lhe application itself for its own purposes. The system handles 
some events before the application ever sees them, and it leaves 
others for the application to handle. 

Each event's type is described by an event code, a numeric value 
that the Event Manager returns to the application getting the 
event. For programming convenience, there is also a set of 
predefined constants for these codes. Table 3-2 lists the codes and 
constants, The first half of the TaskTable in the assembly- 
language version of HodgePodge's main event loop (in the file 
event . ASM) is a code equivalent to Table 3-2; C and Pascal 
HodgePodge, on the other hand, use the predefined constants to 
describe event codes. 

Table 3-2 

Event Manager event codes 



Value 


Constant 


Meaning 





nullEvt 


null event 


1 


mouseDownEvt 


mouse- down event 


2 


mouseUpEvt 


mouse-up event 


3 


keyDawnEvt 


key-down event 


4 




(undefined) 


5 


autoKeyEvt 


auto-key event 


6 


updateEvt 


update event 


7 




(undefined) 


8 


activateEvt 


activate event 


9 


switchEvt 


switch event 


10 


deskAccEvt 


desk-accessory event 


11 


drive rEvt 


device-driver event 


12 


applEvt 


application-defined event 


13 


app2Evt 


application-defined event 


14 


appSEvt 


application-defined event 


15 


app4Evt 


application-defined event 
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From Table 3-2 you can see that 16 is the maximum number x. 
cases your main event loop has to consider If your application 
calls GetNextEvent. If it calls TaskMaster instead, many of these 
events are handled automatically; however, there is an additio 
set of codes, called task codes, returned by TaskMaster. See "I 
TaskMaster," later in this section. 

Event records and masks 

Every event is represented by an event record containing jl.. 
pertinent information about that event. The event record indu 
the following information: 

■ What: the event code, such as mouse-down 

■ When: the time the event was posted (the tick count) 
m Where: the location of the mouse at the time the event 

posted, in global coordinates (see "Global and Local 
Coordinate Systems," in this chapter) 

■ Modifiers: the state of the mouse buttons and modifier keys at 
the time die event was posted, such as Option key down 

m Message: any additional, event-specific information, such as 
which key the user pressed or which window is being activated 

Some of the Event Manager routines can be restricted to operate 
on a specific event type or group of types; in other words, some 
event types are enabled while all others are disabled. For instance, 
instead of just requesting the next available event, the application 
can specifically ask for the next keyboard event. It does so by 
supplying an event mask as a parameter. The mask disables any 
unwanted event types 

There's also a global system event mask that controls which event 
types, the Event Manager posts into the event queue in the first 
place. When the system starts up, the system event mask is set to 
post all events. 



Responding to events 

Here are some typical application responses to commonly 
occurring events. 

♦ Taskmaster: These responses apply to a program that uses 
GetNextEvent in its event loop. If you are using TaskMaster 
instead, see "Using TaskMaster," later in this section. 
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Mouse events 

Mouse- down and mouse-up events occur when the mouse button 
is pressed or released. Mouse movements cause the cursor 
position to be updated, but do not create events. 

On receiving a mouse-down event, an application should first call 
the Window Manager to find out where the cursor was on the 
screen when the mouse button was pressed, and then respond in 
whatever way is appropriate. Depending on where the cursor was 
when the button was pressed, the application may have to call 
toolbox routines in the Menu Manager, the Desk Manager, the 
Window Manager, or the Control Manager. 

[f the application attaches special significance to the user pressing 
a modifier key or keys along with the mouse button, it can 
discover the state of the modifier keys by examining the 
appropriate flags in the modifiers field of the event record. 

If you want your application to respond to mouse double-clicks, it 
must detect them itself. It can do so by comparing the time and 
location of a mouse-up event with the time and location of the 
mouse-down event immediately following the mouse-up event. 

Mouse-up events can be significant in other ways; for example, 
they can signal that the user has stopped dragging the mouse after 
selecting a group of objects. Most applications, however, can 
ignore mouse-up events, and handle dragging with other calls 
such as TrackControl. 

♦ HadgePodge- HodgePodgc does not need to respond to mouse 
events directly. See "Using TaskMaster," later in this section. 

♦ Alternative pointing devices: All applications that use the Event 
Manager work with alternative devices just as they do with the 
mouse. When a device such as a graphics tablet is being used, 
its X-Y location and button status appear in the event records 
in place of the mouse information. Mouse-up and mouse-down 
events are posted when the alternative device's buttons change 
state. 



Keyboard events 

Key-down events occur when character keys are pressed. Modifier 
keys (Shift, Caps Lock, Control, Option, and Apple) generate no 
keyboard events of their own — whenever an event is posted, the 
state of the modifier keys is reported in a field of the event 
record. The character keys also generate auto-key events when the 
user holds them down. 
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Sea "Creating Windows* In 
Chapter 4 fof a discussion of 
window features, 



For a key-down event, the application should first check the 
modifiers field to see whether the character was typed with tfo 
Apple key held down; if so, the user may have been choosing i I 
menu item by typing its keyboard equivalent. 

If the key-down event is not a menu command, the application 
should respond lo the event in whatever way is appropriate, For I 
example, if one of the windows is active, the application could 
insert the typed character into the active document; if none o 
windows is active, it might choose to ignore the event. 

Most applications can handle auto-key events the same way they ] 
handle key-down events. However, you may want your applicatio 
to ignore auto-key events that invoke commands you don't want 
continually repeated. 

**• HodgePodge: The only key events in HodgePodge are thjj 
keyboard equivalents to menu commands. Taskmaster handb 
those events and returns the menu-selection information to 
HodgePodge, so HodgePodge itself needn't respond to ke 
events at all. 



Window events 

To coordinate the display of windows on the screen, the Window 
Manager generates activate events and update events. Activate 
events occur whenever an inactive window becomes active or an 
active window becomes inactive- Update events occur when all or 
part of a window's contents need to be drawn or redrawn, usually 
as a result of the user's opening, closing, activating, or moving a 
window. 

When the application receives an activate event for one of its own 
windows, the Window Manager will already have done all of the 
normal housekeeping associated with the event, such as 
highlighting or unhighlighting the window. The application can 
then take any further necessary action, like showing or hiding a 
scroll bar, or highlighting or unhighlighting a selection. 

On receiving an update event for one of its own windows, the 
application is responsible for updating (redrawing) the contents 
of the window 

♦ HodgePodge: Activate and update events in HodgePodge are 
handled automatically through TaskMaster. 
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Other events 

Device- driver events are generated by device drivers in certain 
situations; for example, an application might set up a driver to 
report an event when its transmission of data is interrupted. 

A desk accessory event occurs whenever the user enters the 
special keysioke (Control-Apple-Escape) to invoke a classic desk 
accessory. See "Supporting Other Desktop Features" in Chapter 5. 

An application can define as many as four application-defined 
events of its own and use them for any purpose. 

Switch events are reserved for future use. 

The Event Manager returns a null event if it has no other events to 
report Most applications ignore null events and continue through 
the event loop. 



for a full discussion of 
TaskMaster, see 'Window 
Manager" in the Apple ItGS 
Toolbox Reference 



Event codes are listed in 
Table 3-2. 



Window regions are discussed 
under "Creating Windows" in 
Crtapter4, 



Using TaskMaster 

TaskMaster is a routine that can handle many standard events. 
Technically, it is part of the Window Manager, and it handles 
window-related events such as drawing, scrolling, activating, and 
updating windows. It is discussed here because it replaces the 
GeLNexiBvent call for an application, and it also does preliminary 
event- ha ndling for mouse-down and key-down events. 

When your program calls TaskMaster instead of GetNexiEvent, the 
following happens: 

1. TaskMaster calls GetNextEvent. 

2 If no event is ready to be handled, TaskMaster returns zero. 

3. If an event is ready, TaskMaster looks at it and tries to handle it. 

4. If Taskmaster can't handle die event, it returns the Event 
Manager event code to your application. The application can 
handle the event as if the event were coming from GetNextEvent. 

5. If TaskMaster can handle the event, it calls standard toolbox 
functions to carry out the task. For example, if the user presses 
the mouse button in an active window's 200m region, 
TaskMaster detects it and calls TrackZoom; it then calls 
ZoomWindow if the user actually selects the zoom region; and 
finally it returns no event. 
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When calling Taskmaster, you pass a pointer to a TaskMaster 
record, the extended task event record. 'Hie beginning of the J 
is the same as an event record, as described under "Event Reo 
and Masks," earlier in this section. When TaskMaster calls 
GetNextEvent, it passes the provided pointer, so the event rec 
part of that record is set by GetNextEvent. The record also indud 
a task mask, similar to the event mask; it tells TaskMaster wh 
types of events to handle. 

Sometimes TaskMaster an handle an event only up to a pom; If t 
user presses the mouse in the active window's content region, Task- 
Master detects it, but won't be able to go any further, so it tells the 
application that a mouse-down event occurred in the active 1 
dow's content region, and lets the application decide what ta 
next. 

Because it only partially handles some events, TaskMaster 
generates its own set of "events" that a program's main event 
loop needs to respond to. Each type of TaskMaster event his a 
task code, a numeric value that TaskMaster returns to the 
application. Just as for the Event Manager events described earlier 
In this section, there is a set of predefined constants for these 
codes. Table 3-3 lists the codes and constants, The second half of 
TaskTable in the assembly-language version of Hodge Podge's 
main event loop (in the file EVENT .ASM) is a code representation 
of Table 3-3; C and Pascal HodgePodgc, on the other hand, 
the predefined constants. 

*> Note.- Many of these task codes are just the results returned I 
the call FindWindow, which TaskMaster makes after calling 
GetNextEvent. 



Table 3-3 
TaskMaster task codes 



Value 



Constant 



Meaning 



16 


wlnDesk 


17 


wlnMenuB-ar 


18 




19 


wlnContent 


20 


wlnDrag 


21 


wlnGrow 


■—•— 


wlnGc-Away 


23 


win Zoom 



in the desktop area 

in the system menu bar 

(undefined) 

in a window's content region 

in a window's drag {title bar) regioi 

in a window's grow (size box) regii 

in a window's go-away (close box) regji 

in a window's 200m (zoom box) region 
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24 


wlnlnf o 


25 


wlnSpecial 


26 


wlnDeskltem 


27 


wlnFrame 


28 


wlnactHenu 


$8xxx 


wlnSysWindo 1 



in a window's information bar 

in the special menu item bar 

(predefined items in the Edit menu) 

in a desk accessory menu item on the 

Apple menu 

in a window, but not in any of Lhe 

above parts of it 

in an inactive menu item 



Together, Table 3-2 and Table 3-3 show that Taskmaster can return 
to your application up to 25 or so events that your main event 
loop may have to deal with. In most situations, though, TaskMastcr 
handles most of them automatically. HodgePodge, as we saw in 
Chapter 2, responds only to task codes 17, 22, and 25 
(wlnMenuBar, wlnGo Away, and wlnSpecial). 

You should use TaskMastcr for at least, two reasons: 

D It can help you get an application running as quickly as 
possible, still taking advantage of the standard user interface, 
TaskMaster represents one of the steps taken to remove the 
most tedious user-interface chores from the application. 

D TaskMastcr will help assure upward compaublity. New, as yet 
unknown, features may be added to the Apple IIGS system in 
the future. It may be possible to incorporate those features by 
modifying TaskMaster without adversely affecting past 
applications. In other words, your application may be able to 
use new features without any modification on your part. 



Drawing to the screen (and elsewhere) 

Any time your deskLop application needs to draw something, it uses 
the Apple IIGS tool set QuickDraw II (and its extension, QuickDraw 
II Auxiliary), QuickDraw II is an adaptation and extension of the 
Macintosh toolbox component QuickDraw — it performs similar 
operations but has been enhanced to support Apple IIGS color. 

QuickDraw It allows you to perform graphic operations easily and 
quickly. QuickDraw draws text in different fonts with styling 
variations such as italics and boldface. It draws lines and shapes 
of various sizes and patterns. It can draw items in a variety of 
colors or in gray scales. 
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The Print M n „™, a ■ „. QuickDraw II can draw to ihe screen or lo other parts of Apple 

S'd^cSSSKS.l^Sr ? 1M ?« «"7. to ** Pining a document with the Print Z & 
and Devices," In Chapter 5. involves using QuickDraw to "draw" your document into a 

memory buffer used by the Print Manager. 

* Note: For brevity, we'll use the terms QuickDraw and 

QuickDraw II synonymously here. Unless otherwise explicitly 
stated, QuickDraw means the Apple HG5 tool sets QuickDrav 
and QuickDraw If Auxiliary, not the Macintosh version. 

To get our bearings, we'll first consider where QuickDraw If draw, 
Then we'll briefy discuss bow it draws, and finally look at whaiil ' 
draws. The chapter ends with two examples that tie together 
several of the key ideas. 



Where QuickDraw II draws 

The question of where QuickDraw draws involves consideration 
of Apple IIGS memory (including screen memory) as well as 
QuickDraw's own internal representation of its drawing universe. 
These are the main concepts: 

J Drawings are stored in Apple IIC5 memory as pixel images, 
ordered collections of bytes that represent rectangular arrays 
of pixels. Screen memory contains a special pixel image— its 
contents are displayed on the computer's monitor. 
3 QuickDraw II draws its text and graphic objects on an abstract |* 
dimensional mathematical surface called the coordinate plans. 
Points on a plane are much easier to visualize and manipulate 
than addresses in memory. Locations on the QuickDraw U 
coordinate plane arc related to pixel-image memory locator 
specific location information supplied to QuickDraw. 
] Quickdraw draws most objects within the context of graphic 
ports. A port is a complete drawing environment and defines 
among other things, a specific part of memory and a spedfk' 
rectangular area on the coordinate plane where drawing can 
occur, There can be many open ports at a time— some for 
drawing to the screen, some for drawing to other pans of 
memory. Different ports' drawing spaces may be separate from 
each other or they may overlap. 
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n QuickDraw II can be made to clip, or constrain its drawing, to 
within limits of arbitrary size, shape, and location. 

a By manipulating two independent sets of coordinates {global 
coordinates and local coordinates), an application can easily 
control both what gets drawn inside a port's drawing space and 
where, on the screen or other pixel image, that drawing space 
appears. 

The coordinate plane 

QuickDraw locates every action it takes in terms of coordinates on 
a two-dimensional grid (Figure 3-2). The grid is QuickDraw's 
coordinate plane; coordinates on the plane are integers ranging 
from -16K to +16K in both the X- and Y-directions. The point 
(0,0), therefore, is in the middle of the grid. Note also that grid 
values increase to the right and downward on the plane; this is 
different from what you might be used to, but it is the same 
direction and order in which video scan lines are drawn. 

Distances on the grid are measured in pixels. Thus a 10 x 10 
"square" on the coordinate plane is equivalent to a rectangle 10 
pixels by 10 pixels on the display screen (which would not be a 
square, of course, because Apple IlGS pixels are not square), Only 
a very small portion of the coordinate plane can be displayed on 
the screen at any one lime — the plane is 32,000 pixels on a side, 
whereas the screen can show a maximum of 640 pixels by 200 
pixels at a time. Figure 3-2 shows the approximate size of the 
screen (and user) compared to the coordinate plane. 

Important QuickDraw must not be asked to draw outside the coordinate 
plane. Commands to draw outside this space will produce 
unpredictable results. They won't generate errors. 

♦ Macintosh programmers: This conceptual drawing space is not 
the same size as that used by QuickDraw on the Macintosh. On 
the Macintosh, the drawing space is 64K by 6AK pixels centered 

around 0,0, thus making the boundary coordinates -32K,-32k 
and 32K,32K. 
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- ' S 39i 



-16.384 




+16,384 



+ 16.384 

Figure 3-2 

The QuickDraw II coordinate plane 

To understand how QuickDraw does its drawing, we need to consii 
how it represents some basic graphic elements. On the coordinate 
plane, grid lines arc- considered to be infinitely thin. A point is 
defined as the intersection of two grid lines, so it also has no 
dimensions. Pixels, on the other hand, have a definite size; they ire 
thought of as falling between the lines of the grid. The smallest 
element that QuickDraw can draw is a pixel, so if it were to draw a 
point at the location (3,3) on the coordinate plane, it must draw a 
single pixel. Out which one? Four pixels touch the point QuickDraw 
defines the pixel corresponding to each point on the plane as the 
pixel immediately below and to the right of the point. See Figure 5-3 
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Figure 3-3 

Grid lines, paints, and pixels on the coordinate plane 






Pixel images and the coordinate plane 

A pixel linage is an area of memory that contains a graphic 
image. The image is organized as a rectangular grid of pixels 
occupying contiguous memory locations, Each pixel has a value 
that determines what color in the graphic image is associated with 
that pixel. 

*> Macintosh programmers.' QuickDraw II's pixel images are 
similar to Macintosh QuickDraw's bit images. The major 
difference is thai a pixel is described by more than a single bit. 

As described above, QuickDraw II draws to the coordinate plane. 
However, ihe coordinate plane is really just an abstract concept. 
Inside [he Apple lies, drawing actually occurs by modifying pixel 
images — that is, by modifying the contents of certain memory 
locations. In particular, drawing something visible on the screen 
involves modifying the contents of screen memory. 

The data structure that ties the coordinate plane to memory Is the 
Loclnfo (for location information) record. The Loclnfo record 
tells QuickDraw where in memory to draw, how the pixel image in 
that part of memory is arranged, and what its position on the 
coordinate plane is. In Pascal, the Loclnfo record definiu'on looks 
like this: 



Loclnfo -= Record. 




portSCB 


Word 


ptrToPix Image 


Ptr 


width 


Integer 


boundsRect 


Rect 


end 
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The scon-line control byte and 
trie differences between 640 
mode and 320 mode are 

discussed further under 'Drawing 

In Color," late; In this section 



The record consists of four fields: 

' S° r f ^ B C Y e P lica of ^ scan-line control byte) cells 
Qu.ckDraw how ma n y bit, per pi* e J fcere arel [h T 
■mage-two for 640 mode, four for 320 mode . 

■ ptrToP£xlmag e f or (mage pointer) i s th e memory addW 
*c image. It points to the first byte of me pixel ZilTttl 
contains the fir S t (upper-leftmost) pixel. P * ' **" 

soTJZ ,n H c pix V^- QuickDraw «^M 

so it can tell where each new row in the imaae staru m«. 
■mage width mus[ be an even mu]tip|e ^^ CBe 

. bo Unds Rect (for boundary rectangle) is a rectangle that rm 
*e pixel Jraage onto the coordinate plane. The Tpcr leH 
m me rectangle corresponds to the first pixel in t£Hm * \\ 
lower-r.ght corner of the rectangle describes the exten to 2 
pixel ima ge (as fa, as QuickDraw is concerned) See t^ 



image r— A 



Image wlcftti . 




Lower ri 
0627) 



Boundary _ 
rectangle 



Pixel image in memory- 



O 



1 byte r> 2 pixels m 640 mode) 



Figure 3-4 

Pixel image and boundary rectangle 

can thinl nf I h b ? Undar ^ rc «angle happens to be. You 
the eS 5 PU£d fmage w havin * lts own private cap < 

SeM^ C °°; dm3te P ' anC t0 &? wiLh ' s ° *" even two 

completely tt^~££ — 
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Windows cnb described further 
under "Creating Windows" In 
Chapter 4. 






GrafPort, port rectangle, and clipping 

Most drawing lakes place in conjunction with a data structure 
called a GrafPort (for graphic port), Each GrafForL contains a 
complete specification of a drawing environment, including the 
location information (Loclnfo record) described above, in 
addition to the location information, a GrafPort contains three 
other fields that restrict where drawing in a pixel image can lake 
place: ihe port rectangle, clipping region, and visible region. 

The port rectangle (or portRect) is a rectangle on the 
coordinate plane. Any drawing in a GrafPort occurs only inside 
its portRect. When you look at a window on the screen in a 
desktop application, its interior (everything but its frame) 
corresponds to a port rectangle. 

The port rectangle can coincide with the boundary rectangle or it 
can be different. You can think of it as a movable opening, 
allowing access to all or part of the pixel image, As Figure 3-5 
shows, QuickDraw can draw only where the boundary rectangle 
and port rectangle overlap. 



Boundary rectangle 



Port rectangle ,, 











Ttg' L 25755006 J '$ 

n m ,2 











Figure 3-5 

Boundary rectangle/port rectangle Intersection 
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The origin of a rectangle, in 
QuickDraw II. Is Its upper-left 
corner. 



The clipping region (or clipRgn) is provided for an application k 
use, When a GrafPort is opened or initialized, the clipping region 
is set to the entire coordinate plane (effectively preventing any 
clipping from occuring). The program can use the dipRgn in any 
way it want. Any drawing to a pixel image through a GrafPort 
occurs only inside the clipping region. 

The visible region (or visKgn) is normally maintained by thil 
Window Manager. An application can have multiple windows cm 
the screen, each one associated with a GrafPort. Windows cm 
overlap, and each port's visible region represents the parts of the 
window that are visible. 

In summary, drawing occurs in a pixel image only in the 
intersection of the boundary rectangle, port rectangle, clipping 
region, and visible region. 

Global and local coordinate systems 

Everything is positioned in QuickDraw's universe in terms of 
coordinates on the plane. However, if you think of multiple open 
windows on the screen, you can see that there are at least two 
different ways in which you might want to locate objects: 

n You may want to specify where windows appear on the screen 
(for example, when they are moved). 

D You may want to specify where objects appear within windows 
(for example, when scrolling), independently of where on the 
screen the windows may be. 

♦ HodgePodge: Because Taskmaster takes care of all window 
events related to tasks such as moving and scrolling, 
HodgcPodge itself doesn't worry about coordinates at all when 
it draws a window, 

The toolbox needs global coordinates whenever more than one 
GrafPort share the same pixel map; the global coordinates tell 
QuickDraw exactly where every port rectangle is compared to 
every other one. The global coordinate system for each Grafroft 
is that in which the boundary rectangle for its pixel map has its 
origin at (0,0) on the coordinate plane. For drawing to the screen, 
you can think of global coordinates as screen coordinates, where 
the upper-left corner of the screen is the point (0,0), 



62 



Chapter 3; Using the Toolbox f, I ) 



However, each port also has its own local coordinate system, lor 
example, when drawing into a port it might be more convenient 
to think in Lerms of distance from the port rectangle's origin 
rather than the boundary rectangle's origin. By defining the port 
rectangle as starting aL (0,0), you can base ail your drawing 
commands on distance in from the left edge and down from the 
lop of the portHecl. 

Thai's convenient for drawing in a window, but local coordinates 
are more of a convenience than that. They aren't constrained to a 
value of (0,0) for the port rectangle origin — you can set them to 
any coordinate-plane value. Why would you want to? Because of 
the way drawing commands work, 

Suppose you are using a window to display portions of a 
document that is larger than the port rectangle in size — a fairly 
common occurrence. You are using drawing commands that draw 
the entire document, and you know that's no problem because the* 
drawing will be automatically clipped to the port rectangle. But 
how do you control which part of the document shows in your 
window? You do it by adjusting local coordinates. 

All QuickDraw's drawing commands are based on the current 
port's local coordinate system. So if location (0,0) in your 
GrafPort's local coordinates corresponds to the port rectangle's 
upper-left corner, any time you draw your document into that 
port, its upper-left corner will be displayed. If you define your 
local coordinates differently, different parts of your document will 
appear in the window. Thus you can think of local coordinates as 
document coordinates- — the upper-left corner of the document 
being viewed in the port has the value (0,0) in local coordinates. 
See Figure 3-6. 
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a. PortRect origin = C0 P 0) 
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Pen location and other pen 
characteristcs ate described 
next, under *How QuickDraw II 

Draws " 



Figure 3-6 

Drawing different parts of a document by 

changing local coordinates 

•> Note- When the local coordinates of a GrafPort are changed, 
the coordinates of the GrafPori's boundary rectangle and 
visible region are similarly recalculated, so (as rioted) lhe j 
will not change its relative position on the screen or in retail 
to other open ports on the screen. 

However, when the local coordinates are changed the 
GrafPori's clipping region and pen location are not 
changed — that is, they appear to shift right along with the 
image that is being viewed in the port. It makes sense to have 
the pen, which is used to modify lhe image being viewed, and ] 
the clipping region, which is used to mask off parts of the 
image being viewed, "stick" to it. 
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How QuickDraw II draws 

How QuickDraw II draws any of its objects depends on the 
drawing environment specified in the current GrafPort. Each 
GrafPort record includes location and clipping information 
(described above), information about the graphics pen 
(described next), information about any text that will be drawn 
(described under "...And Text Too," later in this section), and 
other information such as pen patterns to draw with. 



The drawing pen 

Each open port has its own drawing pen. By means of several 

characteristics modifiable by the application, the pen controls 
where and how drawing (of both text and graphics) occurs. 

Pen location: The pen has a coordinate-plane location (in local 
coordinates). The pen location is used for drawing lines and text 
only — other shapes are drawn independendy of pen location. 

Pen size; The pen is a rectangle that can have almost any width 
or height. Its default size is 1 x 1 (pixels). If either the width or 
height is set to 0, the pen will not draw. 

Pen pattern: The pen pattern is a repeating array (8 pixels by 8 
pixels) that is used like ink in the pen. Wherever the pen draws, 
the pen pattern is drawn in the image. The pattern is always 
aligned with the coordinate plane so that adjacent areas of the 
same pattern drawn at different times will blend in a continuous 
manner. 

Background pattern: The background pattern is an array similar 
to the pen pattern. Erasing is the process of drawing with the 
background pattern. 

Drawing mask: The drawing mask is an 8-bit by 8-bit pattern that 
is used to mask, or screen off, parts of the pattern as it is drawn, 
Only those pixels in the pattern aligned with an on (=1) bit in the 
mask are drawn. Figure 3-7 shows how a mask affects drawing with 
a pattern. 
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AH eight pen modes (also called 
transfer modes) are described 
and diagrammed under 
'QuickDraw II" In the APP'e "gs 
Toolbox Reference. 
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Figure 3-7 

Drawing with pattern and mask 

Note lhat drawing with a mask in which every bit has the value 1 is 
like drawing with no mask at all — all pen pixels are passed through 
to the image. Likewise, drawing with a mask lhat is all zeros is like 
not drawing at all — all pen pixels are blocked. 

Pen mode: The pen mode specifies one of eight Boolean 
operations (COPY, notCOPY, OR, notOK, XOR, notXOK, BIC and 
noiBIC) that determine how the pen pattern is to affect an 
existing image. When the pen draws, QuickDraw II compares 
pixels in the existing image with their corresponding pixels in the 
pattern, and then uses the pen mode to determine the value of the 
resulting pixels. For example, with a pen mode of COPY, the 
existing pixels' values are ignored — a solid black line is black 
regardless of the image already on the plane. With a pen mode of 
noiXOR, the bits in each pen pixel are inverted and then 
combined in an exclusivc-OR operation with the bits in each 
corresponding existing pixel. Figure 3-8 shows a rectangle drawn 
over an existing circle, in both COPY and notXOR mode. I 
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COPV mode 

Figure 3-8 

How pen mode affects drawing 



notXOR mode 



QuickDraw's shapes are 
described next, undo* "What 
QuickDraw tl Draws." 



Baste drawing functions 

QuickDraw draws lines with the current pen size, pen pattern, 
drawing mask, and pen mode. 

QuickDraw draws other shapes (.rectangles, rounded-corner 
rectangles, ovals, arcs, polygons, and regions') in five different 
ways: 

■ Frame; QuickDraw draws an outline of the shape, using the 
current pen size, pen pattern, drawing mask, and pen mode. 

■ Paint: QuickDraw fills the shape, using the current pen pattern, 
drawing mask, and pen mode. 

■ Erase: QuickDraw fills the shape, using the current background 
pattern and drawing mask, 

m Invert: QuickDraw inverts the pixels in the shape, using the 
drawing mask. 

■ Fill: QuickDraw fills the shape, with a specified pattern and 
using the drawing mask. 

QuickDraw draws text as described under "...And Text Too," later 
in this section. 



Drawing to the screen (and elsewhere) 



87 



What QuickDraw II draws 



4J 



QuickDraw II can draw a number of graphic objects into a pixel 
image. It draws text characters in a variety of monospaced and 
proportional fonts, with styling variations that include italics, 
boldfacing, underlining, outlining, and shadowing. It draws straigl 

lines of any length, width, and pattern, li draws hollow orpattem- 
filled rectangles, circles, and polygons. It draws elliptical arcs and 
filled wedges, irregular shapes and collections of shapes. It aba 
draws pictures — combinations of these simple shapes. Figure 3-9 
summarizes them. 
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Figure 3-9 

What QuickDraw II draws 



Points and lines 



A point is represented mathematically by its Y- and X- 
coordinatcs — two integers. A line is represented by its ends — two 
points, or four integers. Like a point, a line is infinitely thin When 
drawing a line, QuickDraw II moves the upper-left corner of the 
pen along the straight- line trajectory from the current pen j 
location to the destination location. The pen hangs below arsd to 
the right of the trajectory, as illustrated in Figure 3-10. 
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Starting 
pen location 



Pen size and 

pattern 



Destination location 





Important 



The line os drawn 

Figure 3-10 
Drawing lines 

Before drawing a line, you can use QuickDraw calls to set the 
current pen location and other characteristics such as pen size, 
mode, and pattern. 

QuickDraw's data structure that defines a point has the vertical 
coordinate first: (yx) rather than (x.y). 



Rectangles 

A rectangle (Figure 3-11) is also represented by two points: its 
upper-left and lower-right corners. The borders of a rectangle are 
infinitely thin. Rectangles are fundamental to QuickDraw; there arc 
many functions for moving, sizing, and otherwise manipulating 
rectangles. 
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Figure 3-11 
A rectangle 

The pixels associated with a rectangle are only those within the 
rectangle's bounding lines. Thus the pixels immediately below 
and to the right of the bottom and right-hand lines of the \ 
rectangle are not part of it. 

Rectangles may have square or rounded corners. The comers of 
rounded-corner rectangles are sections of ovals (described neifj 
they are specified by an oval height and oval width. 



Important 



The QuickDraw data structure that defines a rectangle has 
coordinates In the following order: top, left, bottom, right. Thusfi 
defining coordinates for the rectangle In Figure 3-1 1 are (1 ,2,7j6)J 
may seem strange . but it Is consistent with the (y.x) ordering of 
points. 




Circles, ovals, arcs, and wedges 

Ellipses and portions of ellipses form another class of shapes 
drawn by QuickDraw II. An oval is an ellipse, and it is defined jtl 
like a rectangle— the only difference is that QuickDraw is told to 
draw the ellipse inscribed within the rectangle rather than the 
rectangle itself. If the enclosing rectangle is a square, the resu 
oval is a circle. 

*> Pixel shape: Remember, Apple IIGS pixels are not square. M 
circle on the screen, or a true square, will have unequal 
horizontal and vertical dimensions in terms of pixels. 
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Start angle 




Arc angte 




An arc is a portion of an oval, defined by Lhe oval's enclosing 
rectangle and by two angles (the starting angle and the arc angle), 
measured clockwise from vertical. 

If an arc is painted, filled, inverted, or erased, it becomes a 
wedge; its fill pattern extends to the center of the enclosing 
rectangle, within the area defined by the lines bounding the arc 
angle. 



Polygons 

A polygon is any sequence of connected lines. You define a 
polygon by moving to the starting point of the polygon and 
drawing lines from there to the next point, from that point to the 
next, and so on. 

Polygons are not treated in exacdy the same manner as other 
closed shapes such as rectangles. For example, when QuickDraw II 
draws (frames) a polygon, it draws outside the actual boundary of 
the polygon, because the line-drawing routines draw below and to 
the right of the pen locations. When it paints, fills, inverts, or 
erases a polygon, however, the fill pattern stays within the 
boundary of the polygon. If the polygon's ending point isn't the 
same as its starting point, QuickDraw adds a line between them to 
complete the shape. 




Regions 

A region is another fundamental element of QuickDraw, one that 
can be considerably more complex than a line or a rectangle. A 
region can be thought of as a collection of shapes or lines (or 
other regions), whose outline is one or more closed loops. Your 
application can draw, erase, move, or manipulate regions just like 
any other QuickDraw structures, 

You can define regions by drawing lines, framing shapes, 
manipulating existing regions, and equating regions to rectangles 
or other regions. 

Regions are particularly important to the Window Manager, which 
must keep track of often irregularly shaped, noncontiguous 
portions of windows in order to know when to activate the 
windows or what parts of them to update. 
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Pictures 



Pictures are used for transferring 
data between applications, via 
the Clipboard, See "Scrap 
Manager" In the Appte IIgs 
TooSbox Reference. 



Text mode Is similai to pen mode, 
discussed earlier in this section. 



I 



A picture is a collection of any QuickDraw drawing commands, 
data structure consists of little more than the stored commands, 
QuickDraw plays the commands back when the picture is 
reconstructed with a DrawPicture call. A complex mechanical 
drawing produced from an Apple IIGS drafting program might 
saved as a single QuickDraw II picture. 



...And text too 

QuickDraw II doesn't draw graphic images only — it also does all 
text drawing for desktop applications. As an application 
programmer, you can easily control the placement, sine, style, 
font, and color of display text with QuickDraw calls, 

Your program can provide QuickDraw II with text in a number 
formats: 

■ character; a single ASCII character at a time 

■ Pascal string; a length byte followed by a sequence of ASCII 
characters 

■ C string: a sequence of ASCII characters terminated by a zero 
byte 

■ text block: an arbitrary number of ASCII characters in a buffer 

However it receives the text, QuickDraw II draws it in the same 
way. It draws each character at the current pen location, with the 
current font, using the current text mode, with the current 
character style, and using the current foreground and 
background colors. After drawing each character, QuickDraw 
updates the pen location for drawing the next one. 

Providing QuickDraw with various fonts and character styles 
job of the Font Manager, The Font Manager is a tool set thai 
supports QuickDraw's character-drawing ability by providing an 
application with different fonts and styled variations of fonts, 
you want to allow the user to choose from all of the fonts 
available when the application is run, or if you're developing 
application that requires a specific font, the Font Manager can 
help you. 
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Characters 

To help understand just where text appears and how much space 
it takes up, let's define a few terms. Refer to Figure 3-12. 

Text fonts are made up of individual characters. A character is 
represented in memory as a rectangular array of bits, called a 
character image, representing rows and columns of pixels. The on 
(=1) bits are the foreground pixels; the otfT=0) bits are the 
background pixels. 

Every character in a font has a base line. The base line is a 
horizontal line, in the same position for every character in the 
font. Any foreground pixels of a character image that lie below 
the base line constitute the character's descender (characters like 
p and q have descenders). The ascent line is the horizontal line 
just above the top row of a character (including any blanks); the 
distance from the base line to the ascent line is the font's ascent, 
and is equal to the height of the tallest character in the font, The 
descent line is the line just below the bottom row of the character 
(including any blanks); the distance from the base line to the 
descent line is the font's descent, and is equal in size to the largest 
descender in the font. 

Bach character's origin is a point on the base line that is used to 
position the character for drawing. This point need not touch any 
foreground pixels of the character image. When the character is 
drawn, it is placed in the destination location so that its character 
origin coincides with the current pen location. For many letters, 
the character origin is located on the left edge of the character 
image; then, when the character is drawn, its leftmost foreground 
pixels fall just to the right of the pen location. 

The font height is the sum of the ascent and descent heights, and 
it is the same for all characters in a font, The character width is 
the number of pixels the pen position is to be advanced after the 
character is drawn. It includes the width of the character itself and 
any needed space between it and the next character lo be drawn. 

Font height, ascent, descent, character width, and leading (the 
space between lines of text) are needed for calculating string 
lengths and line spacings when you display text on the screen. 
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A character Image 



Next character 

origin 



The basic commands necessary to draw characters on the screen 
arc quite simple. Recall from Chapter 2 how HodgePodge puts up 
he One moment please../' message when the program loads 



MoveTo(20,20) ; 

SatBacttColor (0) 

S*tFor«Color{15); 

Drawstring ('One Moment Please. 



(move pen to upper left of screen) 
(background color » black} 
(foreground color - white] 
(write the message] 



Once the foreground and background colors arc wt all that's 
needed to display a character string is to move the pen to the 
desired location, and call the QuickDraw routine DrawString. 

Fonts 

Each collection of related characters is called a font. With the 
font manipulation capabilities of the Font Manager, your Apple 
HGS apphcations can show sophisticated text display in a variety 
of fonts, sizes, and styles. ^ 

Th* fonf strike AH the character images making up a font are 
stored in memory as a font strike. A font strike is a long 
rectangular array of bits consisting of the character images of 
every defined character in the font, placed sequentially in order 

abut each other; no blank columns are Left between them. 
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Figure 3-13 
Part of a font strike 



Ihe family name of the Apple IBs 
system font On ROM) Is Shoston 



A given font strike need not contain a character image for every 
possible ASCII code. The font may leave some characters 
undefined; these are called missing characters. Immediately 
following the last defined character in the font strike is a character 
known as the missing symbol, which is to be used in place of any 
missing character. In many fonts the missing symbol is a hollow 
rectangle; in the Apple IlGS system font, it's a white-on-black 
question mark. Whenever the QuickDraw II text-handling routines 
encounter a missing character, they substitute the missing symbol 
for the character. 

Choosing a fonl: Fonts for the Apple IIGS are grouped into font 
families. Individual fonts wiLhin families can have various 
characteristics, as noted in the following list. When your 
application requests a font, the Font Manager searches all 
available fonts and chooses the one that most closely matches the 
request, in these categories: 

■ Name: Every font family has a name. The name refers to both 
plain-styled characters of all sizes, and any styled variations, 
such as bold or italics. 

■ Number: Every font family has a number, also independent of 
point size or style modifications. Every family number is 
unique, and corresponds to a single family name. $0000 
represents the system font. 

Whenever an application requests a font whose family number 
is not available, the Font Manager substitutes the system font. 

■ Size: An individual font has a size, described in points. A point 
is a typesetting measure equal to about l/72nd of an inch 



Drawing to the screen (and elsewhere) 



95 



The Font .Manager can provide both real and scaled fonts A 
real font 1S one that actually exists on disk at a particular poit 
size. Conversely, a scaled font is one that was enlarged or 
reduced by calculation from a font of a different size. The Fc 
Manager may scale a font from an existing size if the request 
size is not available. Real fonts generally have a better screer 
appearance than scaled fonts, 

■ Style: An individual font also has 3 style (or combination of 
styles). The presently defined styles are 

□ Plain 
n Bold 

□ Italic 

□ Underling 
3 Outline 

□ Shadow 

'Ihcre arc two different ways to obtain styled variations of font! 
First, the Font Manager will provide a styled font if one is 
available— one whose characters are designed with (for 
example) bold or italic styling. Second, QuickDraw II can style 
a font— that is, it can produce a bold or italicized version of a 
plain-styled font. In fact, it can produce any combination of 1 
defined styles. 

* Note: Fonts that are already styled will not be further styled Or 
the same manner) by QuickDraw II, regardless of the text 
styling selected. For example, an italic font is not further 
italicized if that option is selected on a style menu However it 
could be underlined. 

♦ Underlining: Text cannot be underlined unless the font's 
characters have a descent value (distance between the base li 
and descent line) of at least 2 pixels. The Apple ITGS system 
font (Shaston 8) has a descent value of 1, and therfore cannot 
be underlined. 



Important 



J?£j?™? iL ° kS f ° r tontS fn fhe ^[rectory coiled FONTS/ i 
£?nf I? ^ ^directory on the system disk. Thte subdirectory must 
contain all fonts (except the system font) that are to be available o 
applications. See Appendix C. avauaoie to 
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DoChooseFont is In the source file 
FONT.PAS. 



Your application can allow the user to select a font by calling the 
Font Manager routine ChooscFont, That's what HodgePodge does 
in its DoChooseFont subroutine, called from the routine DoMenu: 



function DoChooseFont: Boolean; 



(begin DoChooseFont-.} 



var theFent : Font ID; 

dunnty : Integer; 

tmpPort : GrafPortPtr; 

tmpPortRec : Graf Port ; 

famName : Str255; 



begin 



tmpPort ;— G»tPort; 

OpanPort (@tmpPartRee) ; 

theFont := Choo»«Font (desiredFont , 0) ; 

If Longlnt (theFont ) = than 

DoChooseFont :- FALSE 
else 
begin 
desiredFont ;- theFont; 
dummy : - GatFamlrif o (dDesiredFont . EaitiNotn, 

famName) ; 
myReply . f i 1 ename : ■ 

coneat (f airiNamei, 
i i 

IntToString 

( desiredFont. fontsize) ) ; 

DoChooseFont ;- TRUE; 



CloaaFort ([1 tmpPortRec) ; 
SetPort (tmpPort) ; 



end; 



{Save current port-.} 

(„.and open new one, so that 

the current port is not affected) 
{ Bring up a dialog prompting 

the user to select a font] 
{If the user cancels..) 
{ DoChoos eFont unsuc ce s a f ul ) 



{Update global variable DesiredFont} 
{Get the font name from its number-,-} 

(„.and put the font name and size in—} 

(...global variable myReply. filename) 
{DoChooseFont completed successfully} 
{end of IF user doesn't cancel} 

{Close the temporary port-.} 
(,„and restore the current port) 
(End of DoChooseFont} 



ShowFont is listed under 
"Displaying Documents In Ports: 
Two Examples." later In this 
section. 



The ShowFont subroutine in HodgePodge is an example of how 
to draw text strings in a specific font with QuickDraw. It is called 
when a font window is first opened and also whenever it needs to 
be redrawn. 
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Drawing in color 

The video display hardware of the Apple lies includes advanced 
color capabilities, Although tool calls make it unneccessary for 
you to manipulate the hardware directly, knowledge of a few 
background concepts will help you understand the way QuickDraw 
II manipulates the colors on the screen. 

The Apple lies offers two Super Hi-Res graphics modes. Both 
modes have 200 scan lines, but the scan lines differ in horizontal 
resolution — one mode has 320 pixels (the color of each specified 
by 4 bits), and the other has 640 pixels (the color of each specified 
by 2 bits). In changing from 320 mode to 640 mode, the horizontal 
resolution is doubled at the expense of dividing the color resolu 
by four. 

Both modes use a chunky pixel organization On which the bits for 
a given pixel are contained in adjacent bits within one byte), as 
opposed to bit planes (in which adjacent bits in memory affect 
adjacent pixels on the screen). Therefore the 4 bits of a pixel in . 
320 mode are in the same memory locations as the 4 bits of a 
pair of adjacent 2-bit pixels in 640 mode. 

Colors on the Apple II GS are determined from master color values, 
which are mathematical combinations of the primary red, blue, and 
green hues available on a color monitor. A master color value is a 
2-bylc number. The low-order nibble of the low-order byte, controls 
the intensity of the color blue. The high- order nibble of the low- 
order byte, controls the intensity of the color green. The low-order 
nibble of the high-order byte, controls the intensity of the color red. 
The high-order nibble of the high-order byte is not used. Figure 3-H 
illustrates the format of a master color value, 
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Figure 3-14 

Master color value format 

A 3-digit hexadecimal number can describe each master color, 
with one digit (50-SF9 for each primary color. Thus a master 
color value of $000 denotes black, $FFF is white, S0OF is the 
brightest possible blue, $080 is a medium-dark green, and so on. 
Because each primary color has 16 possible values, a total of 4096 
colors are possible. 
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At any one time, the Apple IIGS can display only a small subset of 
all possible colors. An application specifies its colors by 
constructing one or more color tables, short lists of the available 
colors for any one pixel. 

Color tables and palettes 

Applications cannot specify pixel colors directly by using master 
color values. Pixels contain only 2 or 4 bits, and it takes 12 bits to 
specify a master color value, Thai's why color tables are 
necessary. A color table is a table of 16 2-byte enlries. Each entry 
in the table is a master color value; any of die 4096 possible color 
values may appear in any position in the color table. 

An application determines the color of a given pixel by 
specifying an offsel into the color table. The number of bits used 
to describe a pixel limits how far into the table it can reach. The 
colors available to the application, as specified in its color tables, 
constitute its palette. See Figure 3-15. 

Pixels in 320 mode are represented in memory by 4-bit integers. 
Tor each pixel, that 4-bit value is used as an offset in a color tabic. 
With 4 bits, there are 16 possible pixel values, so the palette in 320 
mode is 16 colors — the entire color table. 

Pixels in 640 mode are represented in memory by 2-bit integers. 
With 2 biLs, there are A possible pixel values to offset into the 
color table, so the palette in 640 mode consists of only 4 colors, 
That would seem to leave three-quarters of the color table unused 
in 640 mode, and severely restrict the use of color, but it's not 
really so. 

In the first place, each 4 adjacent pixels in 640 mode use 4 
different parts of the same color table; a color table, then, consists 
of four mini-palettes, which needn't have the same sets of master 
colors. Therefore, although each individual pixel in 640 mode can 
have one of only four colors, groups of four pixels can have a 
total of 16 colors from which to choose. How to use this ability to 
create a large variety of colors is described under "Dithered 
Colors in 640 Mode," later in this section. 
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The scan line control byte Is 
discussed under "The Video 
Displays" In the Apple IPSS 
Hardware Reference and under 
"QuickDraw II" in the Apple ilGS 
Toolbox Reference. 
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Figure 3-15 

Accessing the color table In 32D- and 640 mode 

An application may construct as many as 16 different color tables 
to choose from. Each of Lhe 200 scan lines in Super Hi-Res 
graphics can use any one of the l6 tables. For each scan line, a 
scan line control byte (SCB) decides which color table is 
active. The SCB also controls screen display mode (320 or 640), 
interrupt mode (whether or not to generate an interrupt during 
horizontal blanking), and fill mode (whether or not pixel 
values of zero can be used to fill areas of color in 320 mode). 



Standard color palette (320 mode) 

The standard pnlcite (the default color table) for 320 mode is 
shown in Table $A. In the table, offset means posilon in the color 
table, and value means master color value, the hexadecimal value 
controlling the fundamental red-grcen-bluc intensities. 
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Table 3-4 

Standard palette— 320 mode 

Offset Color Value 


1 

2 

3 

A 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

The standard palette was selected because of its flexibility and 
appearance; we recommend that you use it unless you have a 
specific need to change it. 

Dithered colors in 640 mode 

A3 explained above, only four colors are available for each pixel in 
640 mode. But when small pixels of different colors arc next to eacl 
other on the screen, their colors blend. For example, a black pixel 
next to a white pixel appears to the eye as a larger gray pixel By 
cleverly choosing the entries in the color table we can make more 
colors appear on die screen. This process is called dithering. 

At the same time, in order to preserve the maximum resolution for 
displaying text, both black and white must be available for each 
pixel- This leaves only two remaining colors per pixel to choose 
from, which seems like a severe restriction. But with dithering, you 
can have 6 40- mode resolution for text and still display 16 or more 
colors, if you are willing to resort to a few simple tricks. 



Black 


000 


Dark Gray 


777 


Brown 


84 1 


Purple 


72 C 


Blue 


OOF 


Dark Green 


OB0 


Orange 


F70 


Red 


D00 


Beige 


FA9 


Yellow 


FF0 


Green 


0E0 


Light Blue 


4DF 


Lilac 


DAF 


Periwinkle Blue 


78F 


Light Gray 


cc c 


While 


FFF 
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Consider the following byte with four pixels in it: 



Bit value 
Pixel number 




So Si i , !f bleS mini P aIete s <« shown in Figure MS 

So p,xel 1 s color is determined by entry 1 j n miniDalette 1 LJ\ 

s ?7S ed by ^ x in ™>^« 2 - -Ts-n. vrL 

h. standard 640-mode color tabic: (shown in Table 3-5) then p £ 

SDOO^ Th appe % ] blue ($0OF >- and P*<* 2 and 4 will appj 
CSDOO). The eye will average these colors and see violet. 

There are 16 different combinations of values that a pair of pi J_ 
can assume m 640 mode, meaning that you ttn obtam ,*$£ 
by h s d.thcnng method. To implement it, just make sure that the 

ss ess s? or fimng c °— ° f * '^ H 



Table 3-5 

Standard palette— 640 mode 



OfTiet 


Color 





Black 


1 


Blue 


2 


Yellow 


3 


White 


4 


Black 


5 


Red 


6 


Green 


7 


White 


8 


Black 


9 


Blue 


20 


Yellow 


1 1 


White 


12 


Black 


13 


Red 


14 


Green 


15 


White 



00 
OOF 
FF0 

J H F 

000 
D00 
0E0 
FFF 

000 
OOF 
FF0 
FFF 

000 
D00 
0E 
FFF 






Vaiu* (mfnipalfttte offsef) 




1 

3 



] 

2 
3 



1 

3 

o 
i 

2 

3 
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<$> Black and white: Note that the entries in the minipalettcs for 
the standard 640-mode color table are set up so that black and 
white appear in the same positions in each palette. This 
arrangement provides pure black and white at full 640 
resolution, allowing crisper text display. 



Displaying documents in ports: two examples 

Commonly you may want to have an application open up a port 
and display, within its port rectangle, a portion of a previously 
created drawing or text document. You might even want to allow 
the user to scroll around within that document, showing different 
parts of it in the port. 

This is not as complicated as it sounds. We'll just give you a brief 
idea here of two simple ways to approach it — two of the methods 
used in Hodge Podge. Please consult ibe Apple IICS Toolbox 
Reference for more details. See also "Creating Windows" in 
Chapter 4 for more information on scrolling, 

♦ /Vote- Ultimately, you are likely to want to let the user alter a 
part of a document while viewing it in a port, and be sure that 
the changes made are reflected in updates to the document 
itself. HodgePodge docs not have that capability; you may want 
to add it as a programming exercise. 

Pixel images 

The keys to displaying a portion of a pixel image in a GrafPort are 
the QuickDraw (and QuickDraw Auxiliary) routines that copy 
pixels from one region to another. One is CopyPbcels, the one we 
use here is PPToPort (for Paint-Pixels-ta-Pori). PPToPort transfers 
pixels from a given source pixel image to the current GrafPort's 
pixel image (the destination pixel image). To use this method to 
view a document you might try the following: 

1, Define a Loclnfo record that describes the offscreen pixel 
image you wish to display. 

2, Open an onscreen GrafPort; its boundary rectangle is the 
screen image boundary rectangle, Make its port rectangle any 
size you wish, up to full screen size. Now anything you draw into 
that port will be visible on screen, 

3, Set your port's local coordinates, to control which portion of 
the image you want to display first. To show the upper-left 
corner of the image, set the port rectangle's origin to (0,0). 
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Palntlt Is in the source file 

PA: NT. PAS 



4 Call PPtoPort to copy the offscreen image onto Lhe onscreen 
re dangle, The call asks QuickDraw to draw the entire image, bd 
because drawing is automatically clipped to the port reccangld 
you only get the part you want. 

HodgePodge uses PPtoPort to draw the contents of its picture 
windows. Here is the routine that does the drawing (Paintlt, 
called by the routine Paint) : 



procedure Paintlt (pict: Handle); 

va.z srcLoc : Loclnfo; 

srcRect: Rect; 

begin 

HLock (pict) ; 

with sicLoc do 
begin 

portSCB :- $0080; 

ptrToPixImage :=- piet A ; 

width ;- 160; 

SefcRact (boundsReet, 0, 0, 640,200) ; 
end; 



(begin Paintlt...) 

(a Loclnfo record} 
(a rectangle) 



(Lock the image's memory block) 
{Define the Loclnfo fields:) 

{set 640 mode) 

{painter to the image} 
{row-width of image in bytes) 
{boundary-rectangle coordinates) 



SetRect (sreRect, q, 0, 640,200) ; 

PPTe-Port [srcLoc, 

sreReet, 

0, 

s re Copy) ; 



HUnLock (pict) ; 



end, - 



{ rectangle to copy FROM} 

(Copy pixels from this Loclnfo...} 
{...and thia source rectangle.,.) 
{-.to location (0,0) in the current...) 
{...GrafPort ' s local coordinates...) 
{...with a pen mode of COPY} 

{ Unlock the image now that we ' re done} 
(End of Paintlt) 



Text documents 

Many documents, such as text hies, have no explicit pixel image 
in memory that represents the contents of the file. If you want 
your application to permit displaying or scrolling through such a 
document in a port, you wouldn't transfer pixels from one image 
to another — you would draw directly into the port you opened. 
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The pixel-based Image of a 
document as seen in a window is 
commonly called the atota area. 
See "Cf eating Windows" in 
Chapter 4. 



ShowFont Is in the source tile 
FONT. PAS. 



Nevertheless, the concept of local coordinates is still important 
and is used identically. Instead of using an actual pixel image 
somewhere in memory, you need to calculate a "virtual image" of 
the document You need to know its exact size, in pixels, and be 
able to place it properly in relation to die port rectangle so that 
the part you want displayed is within the rectangle. Then you can 
set local coordinates accordingly and draw the document to the 
port, knowing that it will be clipped appropriately. 

$ Note: Pascal HodgePodge calculates document height when it 
creates a text window, but it simply assumes a particular width. 
Assembly-language and C versions of HodgePodge, on the 
other hand, calculate document width also, in the routine 
FindJMaxWidth. Sec Appendixes E and F. 

HodgePodge calculates line height in pixels and locates all 
drawing in relation to the document origin— point (0,0)— when it 
displays the contents of a Font window using the routine 
ShowFont. The routine first installs a font Goads it into memory), 
then calculates line height, and then uses that information to draw 
the text. ShowFont is called from the routine pispFontWindow. 



vcedure ShowFont (TheFont ID: Font ID; 
IsMono: Boolean) ; 



font Info : 
currHeight : 

theCh 
currPt 

fontStr 



FontlnfoRec; 

Integer; 

Integer; 

Integer; 

Point; 

Str255; 



begin 

Inat&llFont [TheFont ID, 0) ; 

GatFontlnfo (font Info) ; 

currHeight := fontlnfo. ascent + 

font Info. descent + 
fontlnfo- leading; 

i :■= QatFaunlnfo (TheFontlD.f amNum, fontStr) ; 
fontStr :- concat (fontStr, ' ', 

IntToString 
(TheFont ID, font size) > ; 

i :- GatFontFlags ; 
if IsMono then 

i ;- BitOr(i,S000I) 
else 

i :- EitAnd(i,SOO00); 
SatFontFlag* (i) ,* 



(Begin ShowFont...! 

{a record to hold font information} 
(line height of selected font) 



{string variable to hold characters J 



(Load the font into nssmory-.) 

I ...and store its data in Fontlnfo) 



(Calculate the font's line height} 
(Get the font's name...} 



(..jnake a title string with 

font's name and size) 

(Get current mono/prop . setting) 

(If menu selection says "irono",.} 
(...set bottom bit = fixed width} 
(Otherwise: } 

{Clear bottom bit - proportional) 
(Store result in font flags} 
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MoveTo (S, curr Height) ; 
Drawstring < fontStr} ; 



(Now draw the lines of text:) 

[Move pen to start of first line) 
(Draw the title string} 



DrawStrinaf f^Kip a line, move to start of next) 

■ Tt, D „.■ i. v . (Draw second line) 
me quicJt brown fox jumps over the lasy doo. ')• 
MoveTo[5,currHeight*<3); 
Drawstring ( 

, q , * . ,, (Draw third line) 

fciie sells sea shells down by the sea shore. '); 



MoveTo (5 J .currHeight*5J ; 
for i := to 7 do 
i>scrin 
GetJ?©n(currPt}; 

MoveTo(5,currPt.v + eurrHeight) 
theCh :- i * 32; 
for j i- 1 to 32 ab 
begin 
fontStr[j] := chr(theCh); 
Inc (theCh) ; 
end' 

fQntStrfO] := chr(32); 

DrawString (fontStr) ; 



end,' 



ant:; 



(Now draw all characters in the font:.} 
{Tor each of 7 lines...) 



(starting at current pen location*.) 
(...drop to start of next line) 
(...calculate starting character.,.} 
(For each of 32 chars, in the line...} 

(put the character into fontStr] 

{go to the next character} 

(end filling fontStr for this line} 



■■' 



[How set the length byte to 32...) 
{...and draw the character string} 

(end of drawing the line} 
(End of ShowFont) 
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This chapter continues the discussion of the Apple IIGS Toolbox 
Starting up, handling events, and basic drawing to the screen were 
covered in Chapter 3; here we look at tool sets that help you 
create windows, dialog boxes, and alerts. Chapter 5 presents the 
remaining tools. 



Creating windows 

A window is basically a pott rectangle with a frame; when you 

^iSsa^sssa "T a r d r ow you c r e a GraJPon - a,ong with some 

Chapter 3. additional information that makes a window, When you draw into 

a window, you are drawing into the port rectangle of the GrafPort 
associated with that window. The Window Manager is the Apple 
IIGS tool set that creates these "ports with frames," keeps track of 
their characteristics, and makes it easy for you to deal with the 
fact that there may be multiple, movable, scrollable, overlapping 
windows on the screen at any one time. 



Window basics 

To begin to understand windows, let's look at some basic 
concepts, specifically; 

a how windows relate to GrafPorts 

□ what data structures define a window's features 

Q what types of window frames and controls are available 

□ what window regions are, and how the content region of a 
window relates to its data area 

Windows and GrafPorts 

It's easy to use windows — a window is a port that your application 
can draw into conveniently with QuickDraw II routines. When you 
first create a window, the pixel image and boundary reclangle'for 
its GralPort correspond to the entire screen (QuickDraw ii's 
default assignment), and the pen pattern and other characteristics 
arc also the default values for a GrafPort. You can accept these 
default characteristics unchanged, or you can easily change them 
with QuickDraw II routines. 
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But there is more to a window than the port in which the 
application draws. The other part of a window is called the 
window frame. It usually surrounds the window, and is not part of 
the window's GrafPort. You don't draw into the window's frame 
area directly — the Window Manager takes care of that. 

♦ Note: For drawing window frames, the Window Manager uses a 
GrafPort that has the entire screen as its port rectangle; this 
GrafPort is called the Window Manager port. 






For examples of the use of these 
fields In HodgePodge, see the 

listings of Poinf or 
CHspFonfWIndow under 'Handle 

Specific Events* In Chapter 2. Bee 
also the listing of the routine 
DoTheOpen, under "Opening a 
Window: An Example." later in 
this section. 



Window records and templates 

The Window Manager keeps all the information it requires for its 
operations on a particular window in a window record. The record 
consists of the window's GrafPort record plus other information 
the Window Manager needs to manage windows. Application 
access to record information is restricted to calls through the 
Window Manager and directly to the GrafPort part of the window 
record. As in the case of any toolbox records, accessing their 
fields through calls instead of reading them directly, helps to 
guarantee that your application will remain compatible with 
future toolbox revisions. 

When you create a new window with the NewWindow call, you pass 
the Window Manager a NewWindow parameter list, a template that 
defines the details of the window to be created, including its size 
and location and what controls it will have. The Window Manager 
uses this information to construct the window's record. Three 
fields in the NewWindow parameter list are worth specific 
mention: 

□ wFrame, a set of bit flags that controls, among other things, 
whether the window is to have frame scroll bars. Simply by 
setting bits in this field, HodgePodge specifies that its windows 
are to have both horizontal and vertical scroll bars. 

D wRefCon, which can have any contents an application wants. 
HodgePodge uses this field to store a pointer to information 
about the type of window (font or picture) being created, 

□ wContDef Proc, which, if nonzero, contains a pointer to a 
routine (definition procedure, or de/Pivc) that draws the 
contents of the window. HodgePodge stores pointers to the 
routines Paint or DispFontWindow in this field 
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Window frames and controls 

There are two kinds oF predefined window frames, document and 
alert. Figure 4-1 illustrates them. 



Soma of the standard window 
parts are controls. Controls ate 

described in moie detail In the 

following section, "Putting 
Controls In Windows," 



Clicking refers to pressing and 
releasing the mouse button while 
the mouse pointer Is stationary on 
the screen 



Dragging fefers to pressing 
the mouse button to select 
something and holding the button 
down while moving the mouse, 



Document window frame 

Figure 4-1 
Window frames 



AJert window frame 



The alert window is used by the Dialog Manager; see 
"Constructing Dialog Box.es and Alerts," later in this chapter. The 
document window is what an application typically uses. Inside a 
document window can be standard window parts, which include 
the following: 

■ Tide bar, a rectangle at the top of the window that displays the 
window's title, may hold the close and zoom boxes, and may 
be a drag region for moving the window, 

■ Close box (go-away box), a small square in the title bar that 
the user clicks on to remove the window from the screen. 

■ Zoom box, a small square in the tide bar that die user dicks on 
to alternately make the window its maximum size or return it to 
its previous size and position, 

■ Right scroll bar, a rectangle on the right side of the window that 
the user manipulates to scroll vertically through the data shown 
in the window. 

■ Bottom scroll bar, a rectangle at the bottom of the window that 
the user manipulates to scroll horizontally through the data 
shown in the window. 

■ Sl?,e box, a small square at the lower-right corner of the 
window that the user drags to change the size of the window, 

■ Information bar, a rectangular area where the application can 
display information that won't be affected by the scroll bars. 
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These standard parts may be used in document windows only; 
ihey may not be added to alert windows. They are illustrated in 
Figure 4-2. 



Title bar 
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Bottom scroll bar 



Figure 4-2 

Standard window controls 






Color in an application should be 
designed carefully. Please refer 
to Human Interface Guidelinss: 
fits Apple Desktop tnt efface for 
suggestion*. 






It's possible to define your own 

type of window, such as round or 
hexagonal. See trie Apple IIgs 
Toolbox Reference for more 
Intoi motion. 



A document window may have any or all of Lhe standard window 
parts The only restrictions are that if there is a close or zoom box, 
there must also be a title bar, and if there is a size box, there must 
also be a vertical scroll bar. Common sense suggests that there be 
a zoom box if there is a size box, but this is not a requirement. 

♦ Color: You can specify the colors of the frame and controls of 
a window you create. Colors are selected from a color table. 
See "Window Manager" in the Apple IICS Toolbox Reference 
for details. 

You can use the standard window types, or you can create your 
own window types. Some windows may be created indirectly for 
you when you use other parts of the toolbox — for example, the 
Dialog Manager creates a window to display an alert. Windows 
created cither direcdy or indirectly by an application are 
collectively called application windows. There's also a class of 
windows called system windows; those are the windows in 
which desk accessories are displayed. 
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Aregtoniso grophlc object 
defined by QuickDraw II. See 
"Drawing to the Screen" in 
Chapter 3. 



The routines Palntlt and ShowFont 
In Chapter 3 show how 
Hodge Podge represents the 
data areas of Its windows. 



How scrolling Is accomplished is 
described later In this section 
under "Handling Window- 
Related Events." 



Content region and data area 

A window is composed of regions. The window as a whole (the 1 
structure region) is made up of the content regionand the frame 
region-. 

a The content region is bounded by the rectangle you specify I 
when you create the window (that is, the port rectangle of the 
window's GrafPort), The content region is where your 
application presents information to the user. 

a The frame region is the rest or the window, It may include 
several subregions that correspond to the locations of the 
standard window parts described earlier. When the user 
manipulates a certain control, the Window Manager sees it as 
an event occurring in a certain subregion. See "Handling 
Window-Related Events," later in this section. 

The content region of a window is what the user "sees" within the 
window. It commonly represents a larger area, containing mareB 
information than the screen can display at one time. The windoB 
is then like a microfiche machine — what is seen at any one timej 
in its content region, like what is seen in a microfiche viewer, 
might be only a small portion of the window's entire data area, | 
equivalent to the microfiche sheet. 

The data area is a pixel-based "picture" of whatever document it 
being displayed in the window. For a pixel image (such as a 
HodgePodge picture file), the data area is the pixel image itself. 
For a text document (such as a HodgePodge font window display 
the data area is a conceptual representation of what the docume 
would look tike if it were a pixel image, The document doesn't 
exist in that form anywhere; the appropriate parts of it are 
calculated and drawn in the window's GrafPort each time the 
window is drawn or updated. 

Scroll bars are the controls used to scroll the data area through 
the content region of the window. The size box and zoom box ; 
used to display more, or less, of the data area at one lime. When 
the window as a whole is moved to another locadon on the 
screen, the data area is moved with it, so the view in the content 
region remains the same. 
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Figure 4-3 

A window displays port of its data area 



A window's plan* Is Its front-to- 
back position on the- screen, in 
relation to other windows 



Handling window -related events 

The Window Manager's principal function is to keep track of 
overlapping windows. Your application can draw in any window 
without running over onto windows in front of it. You can move 
windows to different places on the screen, change their plane, or 
change their size, all without concern for how the various windows 
overlap. The Window Manager keeps track of any newly exposed 
areas and provides a convenient mechanism for you to ensure 
that they are properly redrawn. 

There arc two ways to handle user input in relation to windows. 
You can poll the user with the Event Manager routine 
GctNextEvcnt, or with the Window Manager routine TaskMastcr, 
which handles most events dealing with standard user interfaces. 
See "Using TaskMaster™ in Chapter 3. 
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Compare these results from 
f , n d vv i ■ i d o vv w Itti the resk M ast« 
task codes In Table 3-3. 



If you are using GetNextEvcnt, you should call FindWindow every 
lime a mouse-down event occurs, to see if the mouse button was 
pressed inside a window, The FindWindow call determines which 
region is affected, and returns the information to you. The 
following are the various subregious recognized by FindWindoiw 
and the standard actions to take in each case. 

□ The content region has already been described. 1/ the mousefi 
button is pressed in a window's content region, call 

Select Window if the window is not the active window. Otherwise 
handle the event according to your application. 

D The drag area corresponds to the window's title bar (except for 
the close and zoom boxes, if present). Dragging in this 
subregion pulls an outline of the window across the screen, 
moves the window to a new location, and makes it the active 
window (if It isn't already). 

If the mouse button is pressed in a window's drag region, call '. 
DragWindow. 

□ The go-away area corresponds to the close box in the window^, 
title bar. Clicking in this subregion closes the window. 
Depending on your application, the window may disappear 
permanently or simply become hidden. 

If the mouse button is pressed in the active window's close box, 
call TrackGoAway. If TrackGoAway returns TRUE, call 
CloseWindow, or HideWindow, perhaps after saving whatever 
the user was working on inside the window. You may also want 
to close any disk file associated with the closed window. 

□ The zoom area corresponds to the zoom box in the windows 
title bar. Clicking in this subregion toggles between the currer^j 
position and size, to a maximum size and back again. 

If the mouse button is pressed in the active window's zoom 
area, call TrackZoom. Tf TrackZoom returns TRUE, call 
Zoom Window, 

□ The grow area corresponds to the size box in the window's 
lower-right corner. Dragging in this region pulls the lower-rigb 
corner of an outline of the window across the screen with the 
window's origin fixed, and then resizes the window when the 
mouse button is released. 

It the mouse button is pressed in the active window's grow area 
call GrowWindow, When the button is released, call 
Size Window. 



, 
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□ The menu bar is no: a window subregion, but a result returned 
by FindWindow that means "not on the desktop." 

If the mouse button is pressed somewhere outside the desktop, 
it is most likely in the system menu bar. Call MenuSeleet. 

4* Inactive window: Clicking in any region (other than the drag 
region) of an inactive window should have no effect other than 
making it the active window. It is brought to the front and 
highlighted to indicate that it is active. 

♦ Taskmaster: If you are using TaskMaster, it calls FindWindow for 
you. It also calls MenuSeleet, DragWindow, TrackGoAway, or 
other appropriate calls depending on the results of 
FindWindow, In general, you needn't handle any window- 
related mouse events, except possibly in the content region of 
an active window. TaskMaster may not know what you want 
drawn in an active window. 



The v&ete region is the portion of 
a window that Is not offscreen or 
hidden by other windows. St is one 
of The Beldsin a GrafPortttiat clips 
drawing commands. See 
"Drawing to the Screen" in 
Chapter 3. 

Th9 update region Is the portion of 
a window thai needs to be 
redrawn, It may be a part 
exposed by moving or dosing 
another window, or It may be a 
new part of the data arsa 
exposed during scrolling. 



Drawing or redrawing a window 

When a window is drawn or redrawn, the window frame is drawn 
first, followed by the window contents. The Window Manager 
handles all frame drawing. 

When a window's contents need to be redrawn, the Window 
Manager generates an update event that includes a pointer to the 
affected window in the message Held of the event record. Your 
application should respond to update events as follows: 

1. Call BeginUpdate. This procedure temporarily replaces the 
visible region of the window's GrafPort with the intersection of 
the visible region and the update region. It then clears (resets 
to zero size) the update region for that window. 

2. Draw the window contents, Because of step 1 , the redrawing is 
automatically clipped, or limited, to the part of the visible 
region that needs updating. 

3. Call EndUpdate to restore the actual visible region. 

•J* TaskMaster If you use TaskMaster, this procedure is done for 
you, as long as you provide TaskMaster with a routine that 
draws your window's contents (equivalent to step 2, above). 
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♦> HodgePodge: Although it uses TaskMaster and doesn't reallyB 
need an update routine, HodgePodge has a short example of 
an update routine in the code that creates one of its dialog 
boxes. Sec the listing of Showp leas e Wait, under 
"Constructing Dialogs and Alerts," later in this chapter. 

Making a window active 

A number of Window Manager routines change the state of a 
window from inactive to active or from active to inactive. For 
each such change, the Window Manager generates an activate 
event. When the Event Manager finds out from the Window 
Manager that an activate event has been generated, it passes the 
event on to the application through GetNextEvent. 

Activate events for dialog and alert windows are handled by the] 
Dialog Manager, so your application doesn't have to bother wid 
them, In response to activate events for windows created directly 
by your application, you might take actions such as the folio? 

□ Inactivate controls in inacUve windows, and activate controls i 
active windows. 

n In a window that contains text being edited, remove the 
highlighting or blinking cursor from the text when the windo 
becomes inactive, and restore it when the window becomes 
active. 

a Enable or disable a menu or certain menu items as appropriai 
to match what die user can do when windows become active i 
inactive. 

♦ TaskMaster. If you use TaskMaster, highlighting of standard 
windows and controls is handled for you. Enabling and 
disabling of menu items is not. 

♦ HodgePodge: To keep menu highlighting in agreement with 
activate events, HodgePodge calls its subroutine CheckFrontl 
each time through the event loop. 
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Scrolling 



Local coordinates are discussed 
under "Drawing to the Screen" in 
Chapter 3. 



Your application determines how 
many pixels are needed to shift 
frie Image, See 'Putting Controls 

In Windows." later In this chapter, 



Scrolling is ihe process by which the user can bring different parts 
of a document (data area) into view in a window. To accomplish 
scrolling, the user manipulates scroll bars, standard window 
controls managed by the Control Manager. An application (or 
Taskmaster) responds to user manipulation of scroll bars by: 

1. Updating the appearance of the scroll bars to reflect the 
change in position of the daca area. This step is described 
under "Putting Controls in Windows, " later in this chapter. 

2 Showing a new part of the document in the window. The 

application (or TaskM aster) does this by shifting the image in 
the window, then changing the window's heat coordinates and 
redrawing the parts of the data area brought into view. This step 
is described below. 

*• TaskMaster. If your application uses TaskMasier, it can have 
TaskMaster-controlled scroll bars (frame scroti bars) in its 
windows, In that case the application need have no scrolling 
routines at all. The following applies only if your application 
creates and manipulates its own scroll brars. 

♦ HodgePodge: Because it calls TaskMaster, Hodgepodge has no 
scrolling procedure. 

Consider a pixel image, part of which is displayed in a window, 
such as the dollar bill in Figures 3-5 and 3-6. Let's say that the 
window presendy shows George Washington's face (Figure 4-4), 
and the user wants to scroll the image to bring into view the 
circular Federal Reserve seal to the left of Washington. With the 
mouse, the user activates the left-facing arrow on the bottom 
scroll bar. When your application determines that there has been 
a mouse-down event in that part of the scroll bar, it should 
respond as follows; 

1. Call the QuickDraw routine ScrollRect and tell it to move all 
the pixels in the content area of the window a certain number 
of pixels to the right. George shifts a bit to the right. The way 
ScrollRect works, any pixels moved off the right edge of the 
window are lost, and extra pixels added to the left edge of the 
image are blank (colored with the background pattern). 

2. Your onscreen image has been shifted, but QuickDraw hasn't 
automatically filled in the new part of the image that has come 
into view. However, ScrollRect returns information to you that 
tells you exactly what part of your window needs redrawing. Call 
InvalRgn to add that newly exposed area to the window's 
update region, 
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See the toolbox reference for 
instructions on Installing a control 
action procedure. 



3. Call BegintJpdate. 

4 Call your routine that draws window contents. What that routine 
should do is: 

a, Set the local origin to its scrolled value: what it was the las I 
time the window's contents were drawn PLUS the (negative 
value of the) number of pixels that ScrollRect shifted the 
image. 

b. Draw the window's contents (perhaps by calling PPToPort), 
The image is properly shifted and clipped so that just the 
needed part is drawn, There's the seal! 

c Set the local origin back to (0,0). 

5, Call EndUpdate. 

If you put the above steps into a control action procedure, they 
will be called repeatedly as long as the user holds the mouse 
button down with the pointer in the scroll bar. The image will 
scroll continuously. 

Alternatively, if continuous scrolling is unnecessary, you can 
ignore steps 3 through 5. The InvalRgn call causes the Window 
Manager to generate an update event for exactly that part of the 
window, and the next time through the event loop, your regular 
update routine redraws the window. The redrawing won't happen, 
though, until the user releases the mouse button. 
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HMHB1MI 

ED STATES OF AMERICA 

L 25755006 J- 




a. Part of a document displayed 
in a GrafPorf 






:> 



H) STATES OF AMEWq 




b. Application scrolls Image to 
the right. Pixels moving off right 
edge are lost; new area filled 
with background pixels, 



lflMUHn.WiIKlME.UI 



IS OF AMEBIC 

L 25755( 



^MSNIWTI 




c. Application updates the new 
area scrolled Into view by shifting 
coordinates and redrawing. 

Figure 4-4 

Scrolling a pixel image in a window 
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Important When a window is c reated , the Wind ow Manager assigns 1 ts port 
rectangle origin a value of r.0,0) in [oeal coordinates. Whenever It 

redraws the window frame, the Window Manager requires the orlg 
to have that same value. 

Therefore, every time you draw your window's contents you shoulc 
(1) set the origin to whatever Is appropriate, (2) draw the contents, j 
and then (3) restore the origin to (QD) t 



The sequence of subroutine calls 
described In this section Is 
diagrammed in Appendix D. 



DoOpenltem Is In the source file 
MENU.PAS. 



Opening a window: an example 

The following example from HodgePodge shows the steps 
involved in allocating the memory Tor, creating, and drawing the 
initial contents of a window. Remember that in HodgePodge then 
are two types of window: one type displays picture files and the 
other displays lines of text using a particular font. 

The sequence starts when the user chooses Open from the File 
menu or Show Font from the Font menu. In either case execution 
passes from De-Menu to the routine DoOpenltem. DoOpenltem is 
very short: 



procedure DoOpenltem; 

■begin 

if wlndex < IastWind then 
if OpenWindow then 

AddtoManu 

else 
else 

ManyWindDia 1 og ; 
end; 



(begin DoOpenltem...) 



{If there's room for another window-,) 
(call OpenWindow. If it opens 0K_.} 
[...add its name to the Windows menu) 

(If 16 windows already open...} 

(pat up a. dialog and disallow open) 
(End of DoOpenltem) 



Note that DoOpenltem calls both OpenWindow (to open the 
window) and AddToMenu (to add the window's name to the 
Windows menu). AddToMenu is described under "Making and 
Modifying Menus" in Chapter 5, If 16 windows are already open, 
HodgePodge does not allow another to be opened. 



120 



Chapter 4: Using the Toolbox (II ) 



OpenWindow Is in the source file 
WINDOW. PAS, 



OpenWindow determines which type of window is to be opened, 
and prompts the user For the necessary information (picture 
filename or font characteristics). It then calls the routine 
DoTheOpen, which actually opens the window. OpenWindow looks 
like this: 



function OpenWindow; Boolean; 

begin 

OpenWindow :- FALSE ; 

if (LoWord (Event. wnfTagkOata -Font Item) then 
begin 
if DoChooaeFont then 
if DoTheOpen then 
OpenWindow :- TRUE 
and 
else 
begin 
if A3ktl3er then 
It DoTheOpen then 
OpenWindow :■= TRUE 
end; 

end; 



(begin OpenWindow...} 



(initial value of function ■ FALSE! 
(if it ia a font window,,.} 

(...and if the user doesn't .cancel,.,} 
(...and if the window opens OK...} 
{OpenWindow completes successfully} 

{if it is a picture window...) 

(..And if the user doesn't cancel.,.] 
{..And if the window opens OK_.} 
(OpenWindow completes successfully} 



(End of OpenWindow} 



DofheOpen Is in the source file 
W1NDOW.PAS. 






The complete format for fhe 
NswWindow parameter list is 
given under "Window Manager' 
In fhe Apple HG$ Toolbox 
Retsronca. 



ftm 






DoChooseFont was described earlier in this chapter, AskUser is 
described in Chapter 5, under "Communicating With Files and 
Devices." 

Once it has all the information it needs, OpenWindow calls 
DoTheOpen to open the window. DoTheOpen looks like a long 
and complex routine, but that's partly because it is two routines In 
one; it handles two types of windows. It also does a lot of 
assignment and initialisation that your programs may not need at 
this point. We'll break its description into chunks to make it easier 
to follow, 

DoTheOpen starts by allocating memory for the window data 
record (a structure defined by HodgePodge), and putting some 
initial values into the NewWindow parameter list, a toolbox- 
defined structure that is a required inpuL to the NewWindow call. 



at ion DoTheOpen : Boolean; 



vai theWindow ; GrafPortPtr; 
myDataHandls: WindDataH; 



theMenuStr : Str255; 
ourFontlnfo : FontlnfoRec,- 



(begin DoTheOpen...} 

{a pointer to our window) 
{a handle to our own window-data 
record — defined in GLOBALS . PAS J 
(window's title for menu display) 
{to hold font infornation} 
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begin 




DoTheQpen :- FALSE ; 


myDataliandle : - 1 


tfindDataH ( 


NftwHandla {aiaeof (WindDataRec} , 




myMemorylD, 




att r Locked+at t rF ixed , 




Ptr(O))),- 


if isToolError then 


Exit; 




with myWind do 




begin 




paramLength 


:- sizeof (ParamList) ; 


wFrameBits 


!- SDDA.0; 


wRefCon 


;- Longlnt (myDataHandle) ; 


SstRect (wZoorti, Q, 26, 520, 190) ; 


wCoJar 


:- NIL; 


wYOrigin 


:- 0; 


wXOrigin 


- 0; 


wDataH 


'« 188; 


wDataW 


- 640; 


wMaxH 


- 200; 


wMaxW 


- 640; 


wScrollVer 


- 4; 


wScrollHor 


- 16; 


wPageVer 


= 40; 


wPageHor 


- 160; 


wlnfoRefCon 


- 0; 


wlnfoHeight 


- 0; 


wFr ameDe f p roc 


- NIL; 


wlnfoDefProc 


- NIL; 


wPlane : 


- -1; 


wStorage : 


- NIL; 


end; 




theMenuStr :- cor 


icat ('-■', 




myReply . filename. 




'\N', 




IntloString ( 




FirstWindltem+wIndex) , 




' \0 , ' ) ; 


with myDataHandl€ 


** do 


begin 




name : — myB 


eply. filename ; 


menuStr :■ the 


MenuStr; 


menu ID :- Fir 


stWi n dlt em+wl n dex ; 


end/ 





(initial value of function = FALSE) 

{get a handle to our record by...} 
{..requesting memory with these...) 
{attributes: size, User ID,} 
{ locked and fixed, J 
{ anywhere ] 

{terminate if memory unavailable) 

(myWind is a window parameter block,) 

(...required input to HewWindow call) 

(Initialize the window's features:) 

{total size of list} 

{this specifies scroll bars, etc.} 

{handle to our window data record} 

{window size £ postion when zoomed) 

{no colors for this window} 

(y-coord. of port rect origin} 

(x-coord. of port ract origin} 

( document height } 

(document width) 

(max. window height to grow} 

(max. window width to grow) 

[amt. to scroll if v. arrow clicked) 

{amt, to scroll if h. arrow clicked) 

{amt. to scroll if v. page clicked} 

{amt. to scroll if h. page clicked} 

{no info, bar for this window} 

{no info bar for this window} 

(no special frame-drawing routine} 

(no special info-bar content routine) 

(make this window frontmost) 

{let Window Mgr allocate the memory) 



(Make a title for the...} 
(...window to appear in„.} 

{...theWindows menu.} 

(In the window-data record..} 

{.Jill in the name field} 
(,..fill in the menu title field) 
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Alter this initial allocation, DoTheOpen sets up Ihe window to 
display either text or a picture, it inserts into the KewWindow 
parameter list a pointer to the procedure that draws the window's 
interior, and sets the remaining fields in the window-data record. 



if I^Word (Event. wmTaskData) - Fontltem then 

myWind.wContDefProc :- 8 DispFont Window; 
with myDataHandle m " do 
begin 
flag :- 1; 

theFont t- DesiredFont; 
isMono := isMonoFont; 
end; 
InstallFopt (desiredFont, 0) ; 
Gatrontlflfo (ourFontlnf o) ; 
myWind . wPataH :*» 15* (ourFontInfo.ascent+ 
ourFontlnf o .descent) ; 
end 

else 
begin 
myWind.wCantDefProc :- SPaint; 
with ITIyDataHandle'" , do 
begin 
flag :- 0; 
pict := picMndl; 
and; 
end; 



J if it is a font window...} 

(DispFont Window will draw contents) 



(1 means it's a font window) 
(store present font ID in theFont 1 
(store present setting of isMonoFont) 

(load the desired font into memory} 
(...get its characteristics™) 
{.,^nd calculate document height — ) 
[15 = 2 + no, of lines in document} 
(end of IF it's a font window} 

{But if it's a picture window..,} 

(Paint will draw contents] 



( means it ' s a picture window) 
(stare handle to desired picture..,} 
{_ {determined by AskUser) } 
{end of IF it' 3 a picture window} 



Now DoTheOpen determines where on the screen the window is to 
appear. Each newly-opened window is offset down and to the right 
from the previously opened window. Recall from SetUpWindows 
(Chapter 2) that ISizFos is the initial position and size of a 
window. 



with myWind do 
begin 
wTitle :- @myDataHandle Art .name; 
SotRact (^Position, 

wXoffset + iSizPo3.hl, 
wYoffset + iSizPos.vl, 
wXoffset + i5izPos.h2, 
wYoffset + iSizPos.v2); 
end; 

wXoffset :- wXoffset + 20; 
wYoffset :- wYoffset + 12; 
if wYoffset > 120 then 

wYoffset ;= 12; 



( In the window^data record.,.] 

(set window title to name field) 

(Add the window dimensions to the„.) 
(...current X- and Y- offsets} 

{end of setting record fields] 

( Then increment o f f set B. . } 

(...to 3et position of next window) 

{ (after 10 windows make another row) } 
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Finally, now that everything is all set up, DoTheOpen creates 
wrndow .toeir. ft uses the KewWindow call, pacing to NewWinai 
the parameter list that DoTheOpen just filled in. y ou can see 1 
the fcl owmg code that opening a window is quite simple and 
snort It is the preparation and initialization that makes the 
routine seem long and complicated. 



end/ 



theWindow ; = N*wW±ndow (myWind) ; 

SfttFort (theWindow) ; 
SstO^iglnMasJcfSrFFE, theWindow) ; 

InltCursojc; 
DoTheOpen := TRUE; 



{Opfen the window— NewWindow 
returns a pointer to it) 
(Make the window the active port) 
(Adjust window origins to make 
dithered colors come out right} 
{Go back to the arrow cursor} 
(DoTheOpen completes successfully} 
{End of DoTheCpen} 



Putting controls in windows 

A control is an object on the lies screen with which the user 
using the mouse, can cause instant action with graphic results 
change settings to modify a future action. Controls are 
fundamental to the concepts behind the Human Interface 
Gmdd.nes; they provide a simple, intuitive interface, permitting 
the user to affect the course of a „ application, if wellXsign Id 
they remforce the feelings of user control, friendliness and 
consrstency that mark a good desktop application. 

hc h L C v^ 01 "r ^ ^ ±e Part ° f [he A PP Ie IIGS To ^ox that 
helps you create and manipulate controls. The Control Manager 

35 SET* operalions ' bu[ its up lo - to ^ ? 

Controls may be of various types, each with its own characteristic 
appearance on the screen and responses to the mouse. EacT 
£S h «J °™ «*** Properties^-such ast 

'nS:^;:r bui conlrols of ^ same ^ behave I 



Types of controls 

Certain standard types of controls are predefined for you Your 
Sons ^defined controls perform a number of 
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■ Buttons cause an immediate or continuous action when clicked 
or pressed with the mouse. They typically appear on the screen 
as rounded-comer rectangles with a title centered inside. 

■ Check boxes retain and display a setting, either checked (on) 
or unchecked (off); clicking with the mouse reverses the setting. 
On the screen, a check box appears as a small square with a 
title to the right of it; the box is either filled in with an X 
(checked) or empty (unchecked). Check boxes are frequently 
used to control or modify some future action, instead of 
causing an immediate action of their own. More than one box 
may be checked at any one lime. 

■ Radio buttons also retain and display an on-or-off setting, 
They're organized into families; only one button in a family 
should be on at a time. Clicking any button on should turn off 
all the others in the family, like the buttons on a car radio. The 
radio buiton that's on is filled with a small black circle. 

■ Dials display a quantitative setting or value, typically in some 
pseudo-analog form such as the position of a sliding switch, the 
reading on a thermometer scale, or the angle of a needle on a 
gauge. The setting may be displayed numerically as well. 

The control's moving part that displays the current setting is 
called the indicator. The user may be able to change a dials 
setting by dragging its indicator with the mouse, or the dial 
may simply display a value not under the user's direct control 
(such as the amount of free space remaining on a disk). 

The standard controls and a few other typical controls are 
illustrated in Figure 4-5, 



Button 1 



Button 2 




3 Check box 1 
H Check box 2 
□ Check box 3 

O Radio button i 
• Radio button 2 
O Radio button 3 



Figure 4-5 

Standard and typical controls 



"Dials 



Ql .1 ■* 
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Scroll bars 

Scroll bars are predefined dials. Selecting the arrows In a scrolll 
bar scrolls data a line at a time (or an analogous number of pixfl 
in the horizontal direction); selecting the paging regions scrolls* 
data a page at a time; and dragging the thumb to any position I 
within the scrolling area locates the window equivalently within I 
the data area. Although each of these components may seemK)| 
behave like individual controls, they are all parts of a single 
control, the scroll-bar type of dial. You can define other dials oi 
any shape or complexity if your application needs them. 

♦ Note: For scrolling, what constitutes a page and what constitutes 
a line are definable by your application. 

Figure 4-6 shows the parts of the vertical and horizontal scroll bits. 



Up arrow - 



Pag 9 -up region - 



Thumb- 



&rm 



Page-down region 

Down arrow - 

r 

m 



•_■ 



Figure 4-6 

Parts of the scroll bars 

Scroll bars are proportional— that is, they show the relationship 
between the total amount of data and the amount viewed (and 
where the view is in the data). As Figure 4-7 shows, the thumb is 
the same ratio to the scrolling area (the total distance between I 
arrows) as the content region is to the data area. 
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When ihe user clicks in a scroll bar, the Control Manager returns 
to your application a part code, telling it what part of the scroll 
bar the event occurred in. Depending on whether it is in an arrow, 
paging region, or thumb, your application probably should scroll 
the document by a different amount. Once you know how much 
the view should be scrolled, you can recalculate the scroll bar 
values to keep the proportions as illustrated in Figure 4-7. Then, 
call SetCtlValue to redraw the scroll bar with the thumb in the 
proper new position. 

♦ Note: Part codes are returned for all types of controls, but they 
are most significant for complex controls such as scroll bars. 

With the SctCtlParams call, you can store in a scroll bar's record 
the current sizes of your document's data area and content region 
(window size). Then you can easily calculate their proportions for 
setting scroll bar values after scrolling or resizing. 



Data Area 



Content region 




Figure 4-7 

Relation of scroll bars to data area 
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Highlighting can mean differed 
things in different instances but It 
often consists of Inverting on 
object- that Is, changing ail Its 
black pixels to white, and vice 
versa , 



Active controls and highlighting 

If the user presses the mouse button when the cursor is over a 
control, the control is usually highlighted; see Figure 4-8. It's 

exlT f K JUSt P3rt ° f a COmr ° J t0 * flighted: ** 
example, ,f the user presses the mouse button when the pointer j 

h, 'I 2 " i'T L" a J Sao11 baf " the arr ° w - "* ** w ^e scroll 
becomes highlighted. 

A control may be active or inactive. Active controls respond K 
the users mouse actions; inactive controls don't. A control she 
be made macuvc when it has no meaning or effect in the cum 

S £*? " an <**" h uT whei1 no doc ™ [ h3s ^ 

L 0pen ' f ° r a SCrol bar whe « lhere '* ^rently nothing to 
scroll io. An jnacttve Control js shown fa some ^ ^ 

depending on its control type. Figure 4-8 illustrates some active 
and inactive controls. 



Sutton 



C^ Check box 
C^ Radio button 



Button 



ESJ 



Active (high lighted) 



□ Check box 
O Radio button 

Active 



Figure d*8 

Active controls and Inactive controls 



Button 

D Cheek box 

; : Radio button! 



S 



inactive 



"The title and outline of a button, check box, or radio button are 
dimmed automatically when the control is made inae've Fiire 
«*«. two different appearance, that an inactive scroll Z 



cai 



You can make a control inactive by setting its value to a particular 
number. You can also render a control inactive by making t 
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Using controls 



Controls and windows 

Every control belongs to a window: when ihe control is displayed, 
it appears within that window's content region; when manipulated 
with the mouse, it acts on that window. All coordinates pertaining 
to the control (such as those describing its location) are given in 
the window's local coordinate system. Even the state of the 
control can be tied to the state of the window. A bit in the 
window's record can be set so the controls in the window will be 
considered inactive if the the window is inactive. See "Window 
Manager" in the Apple IIGS Toolbox Reference. 

♦ Frame scroll bars: Frame scroll bars (manipulated by 

TaskMaster) work the same as other controls, but are part of a 
window's frame region rather than its content region. 

Controls and events 

When GelNextEvent reports that an update event has occurred for a 
window, your application should call DrawConu*ols to redraw the 
window's controls as part of the process of updating the window. 

*> Taskmaster, If you're using TaskMaster, you needn't redraw 
controls that are part of the window frames — TaskMaster takes 
care of it for you, 

When GelNextEvent reports a mouse-down event for a window 
that contains controls, do this: 

1. Call FindWindow to determine which part of which window the 
cursor was in when the user pressed the mouse button. If it was 
in the content region of the active window, continue with step 2. 

2. Call FindControl to find out where the event occurred. 

3. If FindControl indicates that the event occurred in an active 
control, call TrackConlrol to handle user interaction with the 
control. TrackControl handles the highlighting of the control 
and determines whether the mouse is still in the control when 
the mouse button is released. The routine also handles ihe 
dragging of the thumb in 'a scroll bar and responds to presses 
or clicks in the other parts of a scroll bar. 
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4 If TrackContro) confirms that a valid control was selected, do 
whatever is appropriate as a response. (If no control was 
selected, then of course no action is necessary). 

The application's exact response to mouse activity in a control 
that retains a setting depends upon the current setting of the 
control. For example, when a check box or radio button is die 
you'll make a Control Manager call to change the setting and 
draw or dear the mark inside the control. 

* TaskMasier: If your application calls Taskmaster, the above 
procedure is handled automatically for frame scroll bars in 
standard windows, Only if you have other controls will you 
need a control-drawing routine. 

* HodgePodge: Because it uses only window-frame controls, and 
because it calls TaskMaster, HodgePodge has no specific 
routine to manipulate or draw controls. 

Defining your own controls 

In addition to predefined controls, you can also define your m. 
custom controls. Perhaps you need a three-way selector switch, a 
memory-space indicator that looks like a thermometer, a thrustee 
control for a spacecraft simulator, or some other special type of I 
control. Controls and Iheir indicators may occupy regions of any 
shape. 

To define your own type of control, you place a control definitia 
procedure in your application. The Control Manager stores the 
address of the procedure in the cUProc field of the control recc 
when you create the control with a NewConlrol routine. Later, 
when die Control Manager needs to perform a type-dependent 
aoion on the control, it calls the control definition procedure, 
See the Apple lias Toolbox Reference for details. 



Manipulating lists of selectable items 

If your program displays a list of available fonts, files, telephone 
numbers, icons, or other items in a window, it may put them in 
hits, as defined by the Apple IICS Toolbox. A list is a vertical 
arrangement of similar items on the screen, with a scroll bar to 
Lhe right. Each item in the list is selectable, meaning it can be 
highlighted individually, with a mouse dick or other action. 
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The List Manager is the Apple IIGS tool set that creates, manipu- 
lates and supports lists. It relieves you (the programmer) of much 
of the housekeeping involved with building and maintaining 
complicated lists of items the user may select from. Lists created 
by the List Manager are custom controls, called list controls; that's 
why we mention the List Manager here, under the Control 
Manager. 

You create a list as a iisi record, with a specific format. You may 
use the List Manager to sort the list, if desired, and then to create 
the list control. Once the list control is drawn on the screen, the 
user can select individual items or a range of items from the list. 
How your application handles those selections is, of course, up to 
you. 



Constructing dialog boxes and alerts 

Two of the most useful and versatile means of com mmuni eating 
with your application's user are provided by dialog boxes and 
alerts. The Dialog Manager provides these capabilities in a way 
consistent with the Apple Human Interface Guidelines. 

The Dialog Manager is a sophisticated window- and control- 
manipulation tool set. It automatically performs many functions 
your application would otherwise have to manage explicitly 
through Event Manager, QuickDraw II, Window Manager, LineEdit, 
and Control Manager calls. 



What are dialog boxes? 

Your application typically puts a dialog box on the screen when it 
needs more information from the user in order to carry out a 
command. As shown in Figure 4-9, a dialog box resembles a form 
on which the user checks boxes and fills in blanks. 
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Print the document 
* 8 1/2" x 11" paper 



fiance n 



O 8 1/2" x IN" paper i OK ~) 
E] Stop printing after each page 
Title. 



Annual report 



Figure 4-9 

A modal dialog box 

By convention, a dialog box appears slightly below the menu bar 
.s somewhat narrower than the screen, and is centered between ' 

foSotln ^^ ° f lhC SCfeen - U may COnUin 3ny 0f lhe 

□ informative or instructional text 

□ rectangles in which text may be entered (initially blank or 
containing default text that can be edited) 

□ controls of any kind 

D graphics (icons or QuickDraw II pictures) 

□ anything else your application wants 

The user provides the necessary information in the dialog bo 
for example by entering text or clicking a check box, There^s 
usually a button labeled OK to tell the application to accept 
.nformation provided and perform the command, and a button 
labeled Cancel to cancel the command as though it had never 
been g lve n (retracting all actions since its invocation). Some 
dialog boxes may use a more descriptive word than OK- for 
s-mpLcitv, we'll refer to the button as the OK button. There ma 

each in^^ ° nC bUU ° n ^ WiI ' ^° Im * e c ™» 

eacn in a dilferent way. 



ox, 
the 



132 



Chapter 4: Using tha Toofbox ( fl ) 






Modal or modeless 

Most dialog boxes require the user to respond before doing 
anything else. Clicking a button to perform or cancel the command 
makes the box go away; clicking outside the dialog box only causes a 
beep from the speaker. This type of box is called a modal dialog 
box because it puts the user in the state (or mode) of being able to 
work only inside the dialog box. Figure 4-9 is an example of how a 
modal dialog box might look; note that it has no close box. 

One of the buttons in a modal dialog box may be boldly outlined; ii 
is called the OK button (whatever text it may contain). Pressing the 
Return key has the same effect as clicking the OK button; it should 
initiate the preferred (or safest) action in the current situation. If 
there's no boldly outlined button, pressing the Return key has no 
effect. A Cancel button, if present, doses the dialog box and cancels 
the effects of all work done while the box was open. 

Other dialog boxes do not require the user to respond before 
doing anything else, They are called modeless dialog boxes. The 
user can work in a document window on the desktop between 
clicking buttons in a modeless dialog box. Modeless dialog boxes 
can be set up to respond to the standard editing commands in 
the Edit menu. Clicking a button in a modeless dialog box does 
not make the box go away; it stays on the desktop so that the user 
can perform the command again. 

As shown in Figure 4-10, a modeless dialog box typically looks like 
a document window. It can be moved, made inactive and active 
again, or closed like any document window. When you're finished 
with the command and want the box to go away, you can click its 
close box, or you can choose Close from the File menu if the 
dialog box is the active window. 



1 — ^^=^^= 


Change ^^^m 


m 


Find text: 
Change to: 




■V 


Guide Lines 




Guidelines 




Change nt 


xt Change All 







Figure 4-10 

A modeless dialog box 
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Update routines are described 
under "Creating Windows.' 
earlier in this chapter 

ShowPleaseWait and 

Hide PI ease Wait are in the source 

file DIALOG. PAS. 



Some dialog boxes may in fact require no response at all Fa 
example, while an application is performing a timeconsumir, 
process, it can display a dialog box that contains only a message 
telling what it's doing; then, when the process is complete the 
application can simply remove the dialog box. HodgePodge doa 
this with the Showp lea sewait and HidePleaseWait rou 
called up during tool initialization. ShowPleaseWait also 
demonstrates how to bring up a dialog box and show it 
immediately, without even waiting for an update event to tri^ 
its display. It does this by having its own little update routine: 



procedure ShowPleaseWait; 

var * : Rect; 

origPort : GrafPortPtr; 
msgWindPtrs GrafPortPtr; 

begin 

origPort := GatPort; 

msgWindPtr ; = 

GetNwModalDialog (@PlsWtTemp> ; 
SetR»ct(r, 70, 19, 540,200) ; 
NawDItam ( 

msgWindPtr, 1502, r, 15, 

@' Please wait while we sat things up 

0, 0, Pointer (0)) ,- 
BeglnUpdata (ni3gWindPtr) ; 
DrawDlalag (mggWindPtr) ; 
EndDpdate ( m s gW 1 ntiP t r > ; 

end; 



(begin ShowPleaseWait...} 

(rectangle to display dialog in! 
[comran variable with HidePleaseWait) 
{eornr»n variable with HidePleaseWait) 



(Save the current GrafPortJ 

(Open the dialog, with the template-. 

{..created in InitGlobals} 

(Define rectangle dimensions) 

(Create an item for the dialog:} 

(...with these parameters...} 

(...displaying this string-.} 

{..and with these other parameters) 

(Treat this like an update,.,} 

(...manually draw the dialog...} 

(...and end the update -handling) 

(End of ShowPleaseWait J 



procedure HidePleaseWait; 

begin 

ClosaDAalog (msgWindPtr) 
SatEort (origPort) ; 

end; 



{begin HidePleaseWait,..) 



(Remove dialog from the screen) 
(Restore the original GrafPort} 
{End of HidePleaseWait) 
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Figure 4-11 shows what the dialog box created by 
ShowPleaaetfait looks like. It is a message dialog box because it 
requires no response from the user, and disappears on its own 
when no longer needed. 



Please wait while we set things tip. 



Figure 4-11 

HodgePodge message dialog box 



IT you wont to write a custom alert 
sound procedure, see 
"Miscellaneous Tool Set" and 
"Sound Tool Set" In the Apple IIGS 
Toolbox Reference. 



Alerts 

With alerts, your applications have a standardized way to report 
errors or give warnings. An alert box is similar to a modal dialog 
box, but appears only when something has gone wrong or must be 
brought to the user's attention. The alert box is usually placed 
slightly farther below the menu bar than a dialog box. To help the 
user who isn't sure how to proceed when an alert box appears, the 
preferred button to use in the current situation is doubly outlined 
so that it stands out from the other buttons in the alert box. The 
outlined button is the alert box's default button; if the user presses 
the Return key, the effect is the same as clicking this button. 

There are three standard kinds of alerts — Stop, Note, and 
Caution— each indicated by a particular icon in the upper-left 
corner of the alert box. Figure 4-12 illustrates a Stop alert. You can 
put anything you like in the upper-left corner of an alert, including 
blank space. 

The alert mechanism also provides another type of signal: sound 
from the speaker. The application can base its response on the 
number of consecutive times an alert occurs: the first time, it 
might simply beep, and thereafter it may present an alert box. 
The sound isn't limited to a single beep but may be any sequence 
of tones, and may occur either alone or along with an alert box. 
As an error is repeated, there can also be a change in which 
button is the default button (perhaps from OK to Cancel). You 
can specify different responses for up to four occurrences (.stages) 
of the same alert. 
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Hodgepodge's main error handler, CheekoiskError is an 
example of a routine that puts up a Stop alert (Figure 4-12) The 
exact message displayed depends on the particular error that 
occurred CheckDis^Error is listed and described under 1 
Handling ,n Appendix D. Some of its features are described 
under "Item Lists/ 1 later in this section 




Figure 4-12 

HodgePodge Stop alert 



Dialog and alert windows 

A dialog box appears in a dialog window. When you call a Dialoj 
Manager routine to create a dialog, you supply the same kind of 

ZnZT ^ y™"™* * window with a Window Manager 

rouune. You can mandate a modeless dialog window with 
Window Manager or QuickDraw routines, just like any other 
wmdow-^showmg it niding a> moving ^ Qr ^ 

dialog box GrafPon's clipping region with QuickDraw calls. 

todhSr b ?H9T" in r alert WindOW " Y ° U d ° n>t haVfi lh ^ 

T D Ll\ 8 !£? maf ^ hlin 8 *" al« window, howev e , I 

The Dialog Manager chooses the window definition procedure J 
£« all alert windows have a standard appearance and behavSr ' 
The s.ze and location of the box are supplied as part of the 
definition, You don't specify the alert window's pkne ° always 
comes up in front of all other windows. Because an aiert box 
squires the user to respond before doing anything else and the 
response makes the box go away, the applied doesnV 
manipulate the alert window. 
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Item ID's are discussed in this 
section,, under 'Item Lists.' 



Dialog records 

To create a dialog, you pass inTormaiian to the Dialog Manager, 
with which it creates a dialog record. The dialog record contains 
the window record for the dialog window, a handle to the dialog's 
item list, and some additional fields. The Dialog Manager creates 
the dialog window by calling the Window Manager. 

The Dialog Manager passes to your application a pointer to the 
dialog port, which you use thereafter to refer to the dialog in 
Dialog Manager routines or even in Window Manager or 
QuickDraw II routines. The dialog pointer is equivalent to the 
window pointer for the dialog box. It is not a pointer to the dialog 
record or even to the window record. It is a pointer to the 
GrafPort record only. 

You can do all the necessary operations on a dialog without 
accessing [he fields of the dialog record direcdy. To get or change 
information about an item in a dialog, you pass the dialog pointer 
and the item ID to a Dialog Manager routine. You'll rarely access 
information direcdy through the handle to the item. 



II an item Is enabled, the Dialog 

Manager notifies the application 
whenever the user selects the 
Item. 



Items 

A dialog box or alert is a window with items. To create a dialog 
box or an alert, the Dialog Manager needs to know what items the 
window contains. It also needs to know the following information 
for each item: 

a The item type. This includes not only whether the item is a 
standard control, editable text, or other type, but also whether 
it is enabled. 

□ A display rectangle, which determines the location of the item 
within the dialog or alert box. 

n An item ID number uniquely identifying the item in the dialog. 
All subsequent Dialog Manager calls referring to that item will 
need its ID number. 

u Other information specific to certain types of items, such as the 
item's title, its initial value, its colors, its orientation, and 
whether it is visible or invisible. 
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Ra a io button 
Check box- 



User-defined control - 
ScfOll bar- 



User-defined diatog ftem 



Item type 

■^wTll kemS n ° rmaIJy 3ppeSf in diaI °S *«5 aad 
Hcut-iinea constants or combinations of constants See «ni a in« 



icon 



Button 




■# 8 1/2* x 11" paper 
O 8 1/2" x m" p a p er 

Stop printing after each page 
Choose fiJe 



to print: 





My document 
.CoIc.Sheet 
"PlQDfflatf— 





[Progress of printing 



Figure 4-13 

D fa log Item types 

An editable text item (predefined constant - sdif-Ht, ^ ■ v n 

example, if you wan. lo prevent the user lemporarily from 
manipulating an item, you can disable it, 



Important 



item b unchanged in Q ppe Qf o n ce ^^ ° di$GbJM 



of sim ?„ diaS C! * ^"PP 1 * 3 ™* needs to display a number 
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The view rectangle and other 
aspects of UneEdlt are described 

under 'UneEdlt Too! Set" In the 
Apple tIGS Toolbox Reference^ 



Display rectangle 

Each item in the item list is displayed within its display rectangle. 

a For standard controls, scroll bars and user controls, the display 
rectangle becomes the control's enclosing rectangle. 

□ For an editable text item, it becomes LineEdit's view rectangle. 
The text is dipped (not drawn) wherever it extends beyond the 
rectangle. In addition, the Dialog Manager uses QuickDraw II to 
draw a bordering rectangle outside the display rectangle. 

a Static text Hems are displayed in generally the same way as 
editable text items, except that a rectangle isn't drawn outside 
the display rectangle, Also, there are three different formats for 
static text 

O Icons are aligned with the display rectangle's origin. 

*> Note: Clicking anywhere within the display rectangle is 

considered a click in that item. If display rectangles overlap, a 
click in the overlapping area is considered a click in whichever 
item comes first in the item list. 

Item ID 

Each item in an item list is identified by an item ID, a unique 
number within the list. By convention, the OK button in an alert's 
item list should have an ID of 1 and the Cancel button should 
have an ID of 2, The Dialog Manager provides predefined 
constants equal to the item ID for OK and Cancel, as follows: 

ok =1 

cancel = 2 

In a modal dialog's item list, the item whose ID is 1 is assumed to 
be the dialog's default button (unless specified otherwise); if the 
user presses the Return key, the Dialog Manager normally returns 
the ID of the default button, just as when that item is actually 
clicked. 

To conform with the Apple Human Interface Guidelines, the 
Dialog Manager automatically outlines the default button in bold, 
unless there is no default button (that is, no button item with ID 
1). 

♦ Nola- If you don't want a default button, do not create any item 
with an ID of 1 . 
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Example 



MakeATempiuie is in the souice 
file DIALOG PAS. 



MakeATemplate is a routine called by CheckDiskError 
(described earlier and listed in Appendix D) in order to fill in I 
dialog record and the item list for the Hodgepodge stop alert 
shown in Figure 4-12. MakeATemplate describes the basic alert 
box, including what is to happen at each stage, and defines two 
items: an OK button for the user to click, and a static text item I 
contains the error message. 



procedure MakeATemplate ( TheTemplate: 

AlertTempPtr; 
TheStr: StringPtr) ; 

var currentlteml : ItemTenrplate; 

currentltem2; ItemTempIate; 

beg-in 

with TheTemplate" do 
begin 
SatRact [atBoundsRect, 120, 30, 520, 80 >; 



atAlertID 


= 1500; 


atStagel 


- 580; 


atstage2 


= 580; 


at5tage3 


- 580; 


at St age 4 


- 580; 


atlteml 


= G currentlteml; 


atltem2 


■ G current I tem2; 


atltem3 


= NIL; 


end,* 




with currentH 


:eml do 


begin 




itemlD 


■ l; 


Sat Root (j 


temRect.320,25,0,0) ; 


itemEType 


- 10; 


itemDeser 


- 6'QK'; 


itemValue 


- 0; 


itemFlag 


- Q; 


itemColor 


- NIL; 


end/ 





with currentltem2 do 
begin 

itemlD :- 2; 

SetRaet (itemRect, 72, 11, 639, 199} ; 
itemType := 15 + $800 D; 
itemDeser :- Pointer 'TheStr) ; 
itemValue := 0; 
itemFlag ;- 0; 
itemColor ;= NIL; 
end; 
end,' 



{begin MakeATemplate,..} 
(toolbox-defined structure} 

(First define alert box;} 
(bounding rectangle for alert) 



(at each stage, make alert...} 
t -.visible but silent} 

(ptr to first item's template} 
(ptr to 2nd item's template} 
(terminates item list} 
(end of defining box template} 

{Mow define item 1:} 

{ item #1 = default item} 
(display rectangle} 
( it ' s a buttton item} 
{text in button} 
(initial value ■ 0} 
(=default style} 
(no color} 
(end of item 1} 

(Now define item 2;) 



(display rectangle} 

(disabled static text} 

(the string passed to this routine} 

(no initial value) 

(default style] 

(no color) 

(end of item 2} 

(End of MakeATemplate } 
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Using dialogs 

In most cases, you probably won't have to make any changes to 
the dialogs from the way they're defined at their creation. 
However, there are calls to modify items, move controls, or 
change text. If you want [he font in your dialog and alert windows 
to be something other than the system font, call SeiDAFont to 
change the font. 

To handle events in a modal dialog, call the routine ModalDialog 
after putting up the dialog box. If your application includes any 
modeless dialog boxes, they're a bit more complex to handle; 
part of your event-handling will include determining whether 
events need to be handled as part of the dialog box. You can 
support the use of the standard cut, copy, paste, and delete editing 
commands in a modeless dialog box. 

You can substitute text in static text items with text that you specify 
in the ParamText routine. This means, for example, that a 
document name supplied by the user can appear in an error 
message, 



Ths desk scrap is described 

under "Supporting Other Desktop 
Features' in Chapter 5, 



Editing text with Line Ed it 

To provide simple text-editing capabilities needed for dialog 
boxes and other general purposes, the Apple IIGS Toolbox 
includes the LineEdit Tool Set. The routines in LineEdit provide 
basic text-editing capabilities that follow the Apple Human 
Interface Guidelines. These capabilities include 

□ inserting new text 

□ deleting characters that are backspaced over 

□ translating mouse activity or arrow keys into text selection 

□ deleting selected text and possibly inserting it elsewhere 

□ copying selected text without deleting it 

LineEdit uses inverse highlighting to show the current text 
selection, or a blinking vertical bar to show the insertion point. 
LineEdit places cut or copied text into the LineEdit 
scrap — different from the desk scrap. 
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LineEdit is not a complete text editor, ft does no: support 
l more than 256 d, ra per line (except when using 
LETextBox or LETextBox2) 

] S £S? f l; ^ * tCXL aIigned ™* both the left and 
nght margins (except when using LETextBox2) 

l automatic word wrap (except when using lETextBox2) 
o scrolling 
a fonts that kern characters 

G SZ t£2£ °' slyte ™*°" <- "- *-* - 

Q tabs 



SSS°G u, PAT"'"' hssou '"' ie 



Dialog summary: Hodgepodge's "Abo^ybox 

nlT^eZ^\ S Ubr °. U1 " ,C ""' ^P'^ U* "About 

d&taT^KSS —set? shows , how lo ™" ■ 
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procedure DoAbOUt.It.em,* 

var aboutDlog : GrafPortPtr; 

r : Rect .* 

itemHit : Integer; 

applelconP: Ptr; 

applelconH: Handle; 

begin 

SatRact (r r 146, 20, 495, 192) ; 

aboutDlog := tlawHodalDialog(r,TRUE, 0) ; 

SatRact (r, 270, 153, 0,0), * 

NawDItamf aboutDlog, 1, r , Buttonltem, 
8" OK", 0,0, NIL) ; 

SatRact (r,20, 135,0,0); 

applelconP :■ SApplelcon; 

applelconH ;- iApplelcanF; 

NawDItam (aboutDlog, 3, r, 

iconltenrt-itemDisable, 
ApplelconH, 0, 0,NIL) ; 



SatPort (aboutDlog) 
Sat For aCo lor { ) ; 
SetBackColor (15); 



{begin DoAboutltem...} 

(pointer to this dialog) 

{item selected by user} 

{pointer and handle to the Appie„) 

{-.icon created in InitGlobals) 

{- rectangle the dialog appears in) 
{Open the dialog: in rectangle r, 

visible, no reference value) 
{Define a display rectangle and...] 
{-.make a dialog item for it:„.) 
{...the OK button} 

[Define another display rectangle...} 

{..get a, handle to the Apple icon.,.) 

(make it a disabled icon item) 

{For the rest of the text, simply 
write it directly in the port, 
rather than creating dialog items} 

{make sure this is the active port] 
(foreground color = black) 
{background color ■ white) 



MovaTo (4 0,17); 
SatTaxtFaca(8) ; 
DrawString 

(' HodgePodge" ) ; 

SatTaxtFaca (0) ; 
MovaTo (40,27); 
Drawstring 

( ' A potpourri of routines that ' ) ; 
MovaTo (4 0,37); 
Drawstring 

( " demonstrate many features of * ) ; 
MovaTo (4 0,4 7); 
Drawstring 

( ' the Apple IIGS Tools. ') ; 

MovaTo (40,67); 
Drawstring 

(' By the Apple IIGS Development Team' ) ; 
MovaTo (36,77); 
Drawstring 

("Translated to TML Pascal by TML Systems'); 



{move the pen to starting position..,} 
{ (change to outline text) } 

{Draw the first line...} 

{ (go back to plain text) ) 

(Move to next line and continue...) 
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MovoTo (40,87}; 
Drawstring 

Drawstring 

Drawstring 

V4.0', 23-5ep-87') ; 
itemHit := ModalDial g fNIL ,. 
GloBeDIaio g(about01og]| , 



en of,- 



(call Modainialog; it returns when 

any e n a b le d i t «n ia s^^** 

{Close the Dialog when OK clicked} 

(End of DoAboutltemJ 








B Potpourri of routines thot 

oemonstrotemana features of 
the Apple HGS Tools. 

rr«lf?i t ntt Pl TJ I ! S Dml <Wt Team 
Franslat-d to TML Poscol by 7HL Systems 

Copyright Apple Computer, Inc. 

1986-87, flu rights re^erued 

I'M 23-Sep-e? 




Figure 4-14 

The 'About Hodgepodge../ dioJog bm 
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This chapter concludes our brief discussion of the Apple IIGS 
Toolbox, The tool sets described here can help you accompli; 
these tasks: 

a creating menus 

□ supporting other desktop features such as desk accessories 
cul-and-paste 

□ accessing external devices and files 

□ generating and playing sounds 

□ performing mathematical computations 

□ controlling parts of the Apple IIGS operating environment 



Making and modifying menus 



Pull-down menus are an important pan of the desktop 
environment, Menus allow users to examine all choices availabl 
to them at any time without being forced to choose one of thei 
and without having to remember command words or special ke 

The Menu Manager is the Apple IIGS tool set that supports menus 
of the style recommended by the Apple Human Interface 
Guidelines. The user displays a menu by positioning the cursor] 
the menu bar and pressing the mouse button over a menu title. 
The Menu Manager highlights the selected tide (by redrawing iu 
inverted colors) and "pulls down' the menu below it. As long as 
the mouse button is held down, the menu is displayed Dragging 
through ihe menu causes each of its menu items (commands) to 
be highlighted in turn. If the mouse button is released over an 
item, that item is considered chosen, The item blinks briefly to 
confirm the choice, and the menu disappears. 

When the user chooses an item, the Menu Manager tells the 
apphcation which item was chosen, and the application perforn 
the corresponding action. When the application completes the 
action, it removes the highlighting from the menu title, indicating 
to the user that the operation is complete. 

If the user moves the cursor out of the menu with the mouse 
button held down, the menu remains visible, though no menu 
•terns are highlighted. If the mouse button is released outside the 
menu, no choice is made; the menu just disappears and the 
application takes no action. The user can always look at a menu 
without earning any changes in the document or on the screen. 
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All applications should support 
desk accessories. See 
'Supporting Other Desktop 
Features/ later In this chapter, 



Window menu bars are 
described under "Menu 
Manager" In the Appla itss 
Toolbox Reference. 



Menu bars 

A menu bar is an outlined rectangle that holds the titles of all the 
menus associated with the bar. A menu in the bar may be enabled 
or temporarily disabled. A disabled menu can still be pulled 
down, but iis litle and all the items in it are dimmed and not 
selectable. 

The principal menu bar is the system menu bar; see Figure 5-1 . 
There can only be one system menu bar on the screen at one 
time. The system menu bar always appears at the top of the Apple 
I1GS screen; nothing but the cursor ever appears in front of it. In 
applications that support desk accessories, the first Geflmost) 
menu should be the desk accessory menu (also called Apple 
menu, the menu whose title is a colored apple symbol). The desk 
accessory menu contains the names of all available desk 
accessories, and usually the name of a dialog box that gives brief 
information about the application itself. When the user chooses a 
desk accessory from the menu, the title of the menu belonging to 
the desk accessory may appear in the menu bar for as long as the 
accessory is active, or the entire menu bar may be replaced by 
menus belonging to the desk accessory. 



Titles of enabled menus Titles of disabled menus 



Menu bat { 



* File Edit Vie w Special Color 

1IIIIIIIIIIIIIIIIIIIHIIIIIIIIIIIIIIIIIIHI 



Figure 5-1 

The system menu bar 

In addition 10 the system menu bar, your application can have 
various window menu bars. These can appear anywhere on the 
screen and in windows, Window menu bars are provided to give 
you more menu space, particularly because of the limited 
resolution in 320 mode, Window menu bars should be used 
moderately, if at all. 
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A shadowed rectangle Is one that 

appgars to have a thin shadow 
just below and to -the right of If, 
making It appear to stand out 
slightly from the desktop. 



Menu appearance 

A standard menu consists of a number of menu items listed 
vertically inside a shadowed rectangle. Items on a menu maybe 
the text of a command, a solid color, or just a line dividing 
groups of choices. Menus always appear in front of everything 
except the cursor. Figure 5-2 shows a menu with six items, 
including two dividing lines. 




Keyboard equivalent 
Item 

Dividing line 
Mark- 
Disabled Item- 



Figure 5-2 

A standard menu 

Figure 5-2 shows some of the typical variations in an item's I 
appearance: 

□ A mark may appear on the left side of the item, to denote the 
status of the item or of the mode it controls. 

□ An Apple logo followed by a capital letter may appear to the j 
right of the item, to show that the item may be invoked from 
the keyboard (that is, it has a keyboard equivalent). If the user | 
presses the letter key while holding down the Apple key, the 
menu item is invoked just as if it had been chosen from the 
menu, 

O Each item's iext may have its own text style. 

□ An item can be dimmed to indicate that it is disabled and 
can't be chosen. 

□ A dividing line is a separate menu item. Dividing lines should 
always be disabled. 
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See "Menu Manager" In the 
Apple ttGS Toolbox Reference for 

Information on how to create 
custom menus. 



If a standard menu doesn't suit your needs — for example, if you 
want more graphics, or perhaps a nonlinear text arrangement — 
you can write a custom menu definition procedure. The Menu 
Manager will call that procedure when it draws the menu. The 
custom menu can be visibly very different, and yet respond to 
your application's Menu Manager calls just like a standard menu. 
The items in the menu can have any appearance. 



Keyboard equivalents 

Your program can set up a keyboard equivalent for any of its 
menu commands in order to allow the user to invoke the 
command from the keyboard. The character you specify for a 
keyboard equivalent should be a letter that the user can type in 
either uppercase or lowercase. For example, typing either "G" or 
"g" while holding down the Apple key invokes the command 
whose equivalent is "(3 G." 

♦ Note: For consistency among applications, you should specify 
the letter in uppercase in the menu. 



Constructing menus 

It's simple to construct your application's menus. All you need to 
do is define the text of the menu titles and items, and assign ID 
numbers to each menu title and item. 

* Note-. The menu bar does not allow for a large number of 
menus or menus with lengthy titles. If you're having trouble 
fitting your menus into the menu bar, you should review their 
organisation and tides. Furthermore, if your program is likely to 
be translated into other languages, remember that translated 
menu titles may take up more space. 



Menu lines and item lines 

You create menus by constructing a list of menu and item lines, 
and passing a pointer to that list to the NewMenu routine. 
NewMenu parses the menu and item lines, allocates enough 
memory for necessary records, and initializes those records. The 
menu and item lines must remain in memory as long as the menu 
exists. 
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The list must follow a specific syntax; here is an example: 



I 



For o comp!@t© discussion of 
menu- and item-line syntax, 
including a description of oil 
special characters, see "Menu 
Manager" in the Apple IIGS 
Toolbox Rsferenca 



»Title 1\N1 
--Item string 1\S25G 
— Item string 2\N257 
— Item string 3\N25B 

This is a simple list of one menu line and three item lines. The 
first character on the first line is the title character; it denotes the 
start of a menu. The first character on any line other than a tide 
line is the item character, ft denotes an item in the menu. The 
second character in each Jinc can be anything (it is changed by 
the Menu Manager) — here it just repeats the first character. Each 
line is terminated by a return (decimal 13) or a null byte (0), 
Finally, a termination character, different from the menu and item 
character, denotes the end of the list. 

In the example above, ">" is the title character, *-" is the item . 
character, and a period is the termination character. But you may 
use any characters, as long as the title and item characters are 
different, and the termination character is different from the item 
character. (Thus, the title and termination character may be the 
same.) 

Before the terminating character of each line, "N" followed by a 
number specifies the menu and menu item ID number. 

For an example of menu and item lines using multiple special 
characters and different title, item, and terminating characters, see 
the IlodgePodge source code listing of InitGlobals, under 
"Start the Program" in Chapter 2. In InitGlobals Lhc title 
character is ">", the item character is *^\ and the termination 
character is a period. The second character in each line repeats 
the first. You can see from the listing that, depending on how you 
want your menus to appear, the syntax can be quite complex, 

Using just Che "@" symbol in a title provides the Apple logo. The 
<9 must follow the character denoting a menu title, and then be 
followed by an end-of-line mark (carriage return). Do not place a 
space before or after the @„ as you must with other menu titles. 
See the InitGlobals example. 
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Menu and item ID numbers 

ID numbers are assigned in the menu/item line list. The ID 
numbers must be allocated as shown in Table 5-1. 



Important 



A Menu ID must be unique for each menu; that Is, no two menus can 
have the same ID. Similarly, no two Items, whether In the same or 
separate menus, can hove the same Item ID. 



Table 5-1 

Menu ID number assignment 



Hexadecimal 



Decimal Meaning 



Menu ID numbers 
SOOOO 



$0001-$FFFE 


1-65534 


SI i i f 


65535 


Item ID numbers 




$0000 


o 


$0001 - S00F9 


1-249 


$00FA 


250 


$00FB 


251 


S00FC 


252 


S00FD 


253 


SOOFE 


254 


S00FF 


255 


$0100 - $FFFE 


256-65534 


$FFFF 


65535 



Internal use, generally means 
front, or first menu in bar. 

Reserved for application use. 

Internal use, generally means 
end, or last menu in bar. 



Internal use, generally means 
front, or first item in menu. 

Reserved for desk accessory 
items. 

Undo edit item. 

Cut edit item. 

Copy edit item. 

Paste edit item. 

Clear edit item. 

Close command item. 

Reserved for application use. 

Internal use, generally means 
end, or last item in menu. 
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HodgePodgc uses symbolic constants for menu ID numbers in its 
menu- and item-line definitions, ft assigns menu TD's to those 
constants In the file GLOBALS . pas, as follows- 



AppleMenuID 




300 


About Item 


= 


301 


FileMenuID 


= 


400 


Open Item 


= 


401 


Closeltem 


= 


255 


Saveflsltem 


■ 


403 


choosePitem 


■ 


405 


Pagesetltem 


= 


406 


Print item 


■ 


407 


Quit Item, 


= 


409 


EditMenulQ 


= 


5D0, 


Undoltem 


= 


250, 


Cut Item 


= 


251, 


Copyltem 


= 


2 52; 


Pasteltem 


■ 


2 53; 


Clearltem 


= 


254; 


KindowsMenuID 


= 


600; 


NoWindowsItem 


= 


601; 


FirstWindltem 


- 2000; 


FontsMenuID 


m 


7 00; 


Font Item 


= 


701; 


Monoltem 


- 


7 02; 



{reserved ID number) 
(reserved ID number} 
{reserved ID number) 
! reserved ID number) 
{reserved ID number) 



(window menu ID'S are allocated 
dynamically starting at 2000) 



How Hodgepodge sets up the menu bar when the program 
executes is demonstrated in Chapter 2. 
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Accepting user input 



How your application responds Lo menu selections made by the 

SlSf 5 8e!y on whclher or not lhe application «*> 

ZTZIT*™^™ application 'Wta'U, calls GetNexlEvent 
each ume through the event loop. If the user selects a menu item 

1. Tt calls FindWindow, which tin this case) returns to the 
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I Trucking means following 
changes In cursor position 
betwen the time a mouse button 
1$ pressed and when it Is released. 
Tnat way a user's selection Is not 
finalized until the mouse button is 
released. 



Do Men j Is listed and described 
under "Handle Specific Events" in 
Chapter 2. 



2. It then calls MenuSelect, which tracks the mouse, opening 
menus and highlighting selections until the mouse button is 
released. If it is released in a menu selection, Menu Select 
returns to the application the number of the menu and the 
number of ihe item in the menu that was selected. It also 
highlights the menu's title. 

3. The application then branches to the subroutine that handles 
Lhe menu item selected. 

4. When the task is completed, the application unhightights the 
menu title and continues in the main event loop. 

♦ Keyboard equivalent: If the menu item was selected with its 
equivalent keystroke combination rather than with the mouse, a 
key -down event occurs. The application must look at the 
modifiers field of the event record to know that the Apple key 
was pressed at the same lime, meaning a menu selection has 
been made. The application then highlights lhe menu title and 
proceeds from step 3 (above). 

On the other hand, if your application calls TaskMaster instead of 
GeuVext Event each time through the event loop, most of the 
above procedure is handled automatically, For both mouse-down 
and key-down events, TaskMaster takes care of finding out whether 
they represent menu-selection actions. If the user selects a menu 
item with the mouse or with a keyboard-equivalent, TaskMaster 
highlights the menu and returns a task code of wlnMenuBar 
(meaning a menu selection was made), Your application can 
examine the taskData field of the extended task event record to 
see which item in which menu was selected. Then it can branch 
directly to the appropriate subroutine. 

<* HodgePodge: HodgePodgc uses TaskMaster. After receiving a 
wlnMenuBar task code from TaskMaster, HodgePodge jumps 
to its menu-event dispatcher, DoMenu. DoMenu gets the 
individual menu item's ID number from the Event . taskDats 
field of the extended event record, and jumps to the proper 
subroutine. 
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AddToMenu is in the source file 
MENU. PAS. 



Modifying menus during execution 

Jf your menu bar, or items in a menu, are going lo change while 
on the screen, you can use Menu Manager calls to rearrange the 
menus and items. In the routine AddToMenu (called from the 
routine DoMenuItem), HodgePodge adds a new item to the 
Windows menu when a new window is opened on die desktop, 
AddToMenu does this principally by calling InsertMltem and 
Delete MI tern. AddToMenu also adjusts the window fcf— a list of 
pointers to all open windows. 



procedure AddToMenu; 



var theWindow : Graf Port Ptr; 

myDataHandle: WindDataH; 

begin 

theWindow : = FrontWixidow; 

windowList [wlndex.] := theWindow,- 
ntyDataHandle : - WindDataH ( 

GatWRafCon (theWindow) ) ; 

InsartMItam ( SmyDat a Handle *■ * . menuStr [ 1 ] , 
5FFFF, WindowsMenuID) ; 

if wlndex = then 
begin 

Delat<jMlt*m(NoWindowaItem) ; 

SatMenuFlag ( $FF7F , WindowsMenuID} ; 

DrawManuBar ; 
end,* 



{begin AddToMenu...} 



(window-data-record handle} 



'Get a pointer to the front window,.,} 
(add the pointer to the window list) 
{-then get a handle to its,..} 
{...window-data record, to get name} 

(Insert window's name at the end..} 
{...of the Windows jmenu} 

(If this ia the first open window..,} 



(-.remove "No Windows Allocated" 
(...enable the Windows menu...} 
{..jand draw it} 



item} 



end; 



CalcManuSi*£i»(0,0,WindowsMenuID) ; 
Inc (wlndex) ; 



(Recalculate the size of the (nenuj 

' Increment the number of open windows} 

{End of AddToMenu} 



The above example shows how HodgePodge adds iiems to a 
menu. On the other hand, when windows are removed from the 
desktop, HodgePodge deletes the corresponding menu item with 
code in the routine Ad j Wind. Ad j Wind is called from 
DoCloseltem when the user selects Close from the File menu or 
when the user clicks the close box of the frontmost window. 
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, 



c(VWnd is In trie source file 
WINDOW. PAS. 



Ad j Wind makes the menu-related calls InserlMItem, DeleieMItem 
and CalcMenuSize, It also adjusts the window list to reflect the fact 
that a window has been removed. 



procedure AdjWind (TheWindow: GrafPortPtr} ; 



var 



i 
theOne 



Integers- 
Integer; 



(begin AdjWind...} 



begin 

i := FirstWind; 

while windowList [i] <> TheWindow do 
Inc (i) ; 

theOne; -i; 

if wlndex = 1 then 
b&cjln 
Ina«rtMIt«ro<'3nQW±ndStr[ll , 

Fir stWindltem+theOne , 
WindowaMenuIDl ; 
SotManuFlag ( $ 8 , ff i ndow sMenu I D ) ; 
D r awMonuBa r ; 
wXoffset :- 20; 
wxoffset :■= 12; 
end/ 

DeletaMItem(firstWindIten+theOne} ; 
C*lcMenuSIz«i[0,0,WindowsMenuID} ; 

Inc {i ) ; 

while i < lastWind do 
begin 
windowList [i-1] :"*windowList [i] ; 
Inc (i); 
end; 

for i ;- theOne to lastWind do 
SatMItamID (firstWindltem+i-l , 
firstWindltem+i) ; 



(start, with menu ID of 1st window) 
(...and run through the window list} 

{...to get this window's position.) 

{If we're closing the LAST window...} 

(...reinsert "No Windows Allocated"...) 

(..After this itenv..) 

( ...in the Windows menu . } 

(...disable the Windows menu.,.) 

(...redraw the menu bar...) 

(.,.arid reinitialize the position,,,) 

(...of the next -opened window) 

(end of IF its the last win daw] 

{Delete item on the Windows menu...} 
I .,^nd recalculate size of the menu) 

(Now go to the next window on list) 
(...and for each window : r. turn...} 
(move it down one position™! 
{...in. the window list) 



{now renumber items in Windows menu:] 
{its new ID number} 

(its old ID number) 



and; 



(End of AdjWind} 



♦ Note: AdjWind performs some rather complex manipulations 
of pointer lists and menu IDs. Your program can easily remove 
menu items without going through such acrobatics if menu item 
IDs are not going to change and if menu changes do not 
rcquirc adjustment of other lists in memory. 
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Supporting other desktop features 

Two other important desktop-programming features have tool se 
that support them. The Desk Manager controls desk accessories 
(called from the Apple menu) and the Scrap Manager handles 
cutting, copying, and pasting from the Edit menu. 



Just what kind of control an NDA 
exercises is described under 
"Desk Manager' In the AppfettGS 
Toolbox Reference 



Desk accessories 

Any application you write should support desk accessories. Desk 
accessories are short programs such as clock displays, note pads, 
and calculators that a user might want to access without having to 
leave your program, Desk accessory support is a convenience for 
the user, it enhances the multitasking feel of the desktop, and it is 
consistent with the aims of the Human Interface Guidelines, 
Furthermore, it's easy to include in your programs. 

The Desk Manager is the tool set that enables your application to 
support desk accessories. There are two types of desk accessories 
in the Apple IIGS environment: classic desk accessories and new 
desk accessories. 

■ Classic desk accessories (GDA's) are desk accessories designed 
to function in a non-desktop, non-event- driven environment. 
Unlike new desk accessories, a CDA gets full control of the 
computer during what is basically an interrupt state (generated 
by a keypress). The desk accessory is responsible for saving and 
restoring any of the application's memory that it uses, as well 
as handling all I/O. The Control Panel is a classic desk 
accessory. 

■ New desk accessories (NDAs) are desk accessories designed 
to execute in a desktop, event-driven environment. NDA's run, 
in a window and get control when that window is the frontmost 
window. 

♦:♦ Macintosh Programmers? New desk accessories are the style of 
desk accessories available on the Macintosh. 
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See "Contf oiling, ttie Apple IES 
Operating Environment" In this 
chapter, and "The Scheduler" in 
the Appte tf<35 fcc/box Reference 
for more information on the Busy 
lag. 

K you want to write a classic desk 
accessory (CDA). see Chapter 8 
of this book. 



Supporting classic desk accessories 

A user activates a classic desk accessory from the CDA menu. The 

CDA menu is displayed by pressing Apple -Control-Escape at any 

time during program execution. Two CDA's are built into the 

system: 

□ Control Panel 

D Alternate Display Mode 

Any others (up to eleven) are loaded from disk. From the CDA 
menu, a user can select any of the CDA's currently in the system. 
The desk accessory selected is activated and retains control until 
it shuts down. When it shuts down, the Desk Manager redisplays 
Lhe CDA menu. Only when the user selects Quit from the CDA 
menu does the original application resume operation. 

When can the CDA menu be displayed? The Desk Manager gets 
control in two ways. If the Event Manager is active, the Desk 
Manager is called in conjunction with GetNextEvent. If the Event 
Manager is not active, the Desk Manager gets control whenever 
the user presses Apple-Control-Escape, which generates an 
interrupt. Before the Desk Manager displays the CDA menu, it 
checks the system Busy flag. If something in the system is busy, 
the Desk Manager waits until the Busy flag is cleared, then "wakes 
up" and displays the CDA menu, This guarantees that CDA's have 
all system resources available to them when they are called. 

The only thing your application needs to do to support classic 
desk accessories is make sure that interrupts are not disabled for 
long periods 



Supporting new desk accessories 

New desk accessories are loaded automatically by the operating 
system at boot time. An application that wants to make NDA's 
available to the user does not have to do a lot of work, particularly 
if the application is using the Window Manager routine TaskMaster. 
By convention, however, desk accessories can assume that the 
following tool sets arc already available for them to use, so the 
application must make sure that they are loaded and started up; 

□ Tool Locator 

n Memory Manager 

a Miscellaneous Tool Set 

□ QuickDraw II 

rj Event Manager 
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If you wont to write a new desk 
accessory (NDA). see Chapter 3 
of this book 



D Window Manager 

a Control Manager 

D Menu Manager 

a Line Edit Tool Set 

a Dialog Manager 

D Scrap Manager 

With TaskMaster; If the Application uses TaskMaster, it only need 
to make Lhree calls to support new desk accessories after it has 
loaded and started up the proper tool sets: 

o DeskStartup — to initialize the Desk Manager 

G FixAppleMenu — to add to the list of NDA's in the Apple menu 

n DeskShutdown— to shut down the Desk Manager before the 
other tool sets are shut down 

After the FixAppleMenu call has been made, TaskMaster 
automatically handles opening NDA's in response to menu 
selections, calling SystemTask and SystemClick when appropriate. 
If the application sets up the menu items correctly, TaskMaster 
can even call SystemEdit when the user selects an item from the 
Edit menu, or close a desk accessory in response to the user's 
selecting Close from the File menu. 

'** HodgePodge- The three calls listed above are in the routines 
StartUpTools, SetUpMenus, and ShutDownTools. 






Without TaskMaster: Applications that do not use TaskMaster 
must take the following steps to support new desk accessories, 

1. Call DeskStartup to start up the Desk Manager. 

2 Call FixAppleMenu to add to the list of NDA's in the Apple menu. 

3. Call OpenNDA when the user selects an NDA from the Apple 
menu. 

<1. Call SystemTask frequently (at least every time through the 
event loop). 

5. Call SystemClick when a mouse-down event occurs in a system 
window. 

6. Call SystemEdit when a desk accessory is active and the user 
selects Undo, Cut, Copy, Paste, or Clear from the Edit menu 

7. Close the desk accessory when the user selects Close from the 
File menu. You can use CloseNDA or CloseNDAbyWinPtr to do 
this. 

8. Call DeskShutdown to shut down the Desk Manager. 
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Cutting and posting 

An important part of the convenience provided by desktop 
applications is the ability they give the use* to transfer and copy 
fragments of text or graphics within a document, or from one 
document to another. 

The Scrap Manager is the tool set that lets an application handle 
cutting and pasting of the desk scrap. From the user's point of 
view, all data that's cut or copied resides in the Clipboard. The 
Cut command deletes data from a document and places it in the 
Clipboard; the Copy command copies data into the Clipboard 
without deleting it from the document. The Paste command — 
whether applied to the same document or another, in the same 
application or another — inserts the current contents of the 
Clipboard at a specified place. See Figure 5-3. 

An application that supports cutting and pasting may also provide 
a Clipboard window for displaying the current contents of the 
scrap; it may show the Clipboard window at all times or only when 
requested via the toggled command Show (or Hide) Clipboard, 

♦ Note; The Scrap Manager is designed to transfer small amounts 
of data; attempts to transfer very large amounts of data may fail 
from lack of memory. 



Desk scrop 




Clipboard window 



Documents 

Figure 5-3 

The Clipboard and the desk scrap 
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The desk scrap is usually stored la memory, by! can be scored on 
disk (.in the likiCT.Tp BOARD in the SYSTEM subdirectory of (he 
boot volume; if here's not enough room -for it in memory The 
Desk Mincer keeps I rack of whether the scrap is in memory or 
on the disk, m you don't have to worry about loading it first. 

The nature of the data to be hansferred varies according to the 
application: a word processor handles forma lied text; a graphics 
application handles pictures. The Scrap Manager allows for a 
variety of dsca types, and provides a mechanism whereby 
3 ppli cations have some control over how much information is 
retained whim data is transferred. 






Desk scrap data types 

From the user's point of view there can be only one thing in the. 
Clipboard at a time, but the application may store more than ™ e 
version of the information in Lhe scrap, each representing the 
same .Clipboard contents its a different form. Fi>r example, text cut 
from a word processor document may. he stored in the desk scrap 
both as text and as a QuickDraw n pidure. 

Why would an application want to do this? Applications like to 
keep information in (heir own internal format, but they also want 
to be able to communicate via the Clipboard with other 
applications. When a user culs or copies something to the 
Clipboard, the application can put it there two different ways: 
n The internal, way so that a subsequent pa*te. (within the same 

application) can be easily handled Precisely the information 

needed by the application can be transferred. 

~.\ The public way so that if the user tries to paste it into another 
application or desk accessory, the other application can at least. 
deal with it, oven if some information might be Ins!. 

There are two defined public scrap types: texl and picture. 
Apptications must wrile at (east one of these standard types of 
data to the desk .scrap, and must !je able to read boih lypes. 

Using the Scrap Manager 

if your application support* display of the Clipboard, you shouk 
Call the Desk Manager each time through your main even! loop 
see if the Clipboard window needs to he updated. 

When a Cut or Copy command is given, use the appropriate Des 
Manager cal!s 1o write the cut or copied. data to ihe desk scrap. 



i ^0 CihOntftr fv I teinn 7hn Tcnlhf™ if'tiii 



When a Paste command is given, use other Desk Manager calls to 
access the particular type of data in the desk scrap that you want, 
and to get information about the data. 

♦ Edit menu; The user accesses the desk scrap through the Edit 
menu. Whether or not your application supports cutting and 
pasting, it must include an Edit menu. Desk accessories may 
need it 

* HodgePodge- HodgcPodge does not support cutting and 
pasting. It has an Edit menu, but all items are initially dimmed 
(disabled). 



Setting up a private scrap 

If your application defines its own private type of data, or if very 
large amounts of data might be cut and pasted, you may want to 
set up a private strap for this purpose, A private scrap can have 
any format, because no other application will use it. Your 
application must, however, be able to convert data between the 
format of its private scrap and the format of the desk scrap. 

If you use a private scrap, be sure that the right data is always 
pasted when the user gives a Paste command. The right data is 
whatever was most recently cut or copied from any application or 
desk accessory. Make sure also that the Clipboard, if visible, always 
shows the current data. You should copy the contents of the desk 
scrap to your private scrap at application startup and whenever a 
desk accessory (NDA) is deactivated. When your application quits 
or when a desk accessory is activated, you should copy the 
contents of your private scrap to the desk scrap. 

* LineEdit: The LineEdit scrap is a private scrap for applications 
thai use LineEdit. LineEdit provides routines for accessing this 
scrap; you'll need to transfer data between the LineEdit scrap 
and the desk scrap so that the Clipboard will always be current. 

♦ Scrap too targe: If your application has problems copying one 
scrap to another, it should alert the user. If the desk scrap is too 
large to copy to the private scrap, the user may want to leave 
the application or proceed with an empty Clipboard; if the 
private scrap is too large to copy to the desk scrap, the user 
may want to stay in the application and cut or copy something 
smaller. 
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Communicating with files and devices 

The Apple II G5 Toolbox includes several tool sets that handle 
input/output functions. They include 

□ Standard File Operations Tool Set 

D Print Manager 

a Apple Desktop Bus Tool Set 

D Text Tool Set 

Using these tool sets makes your application easier to write and 
ensures a uniform user interface. Almost every application needs 
the Standard File Operations Tool Set and the Print Manager; 
fewer programs need the Apple Desktop Bus Tool Set or the Text 
Tool Set. 



Accessing files 

The Standard File Operations Tool Set provides the standard user 
interface for selecting a file to be opened or saved. The tool set 
displays dialog boxes that allow the user to open and save a file 
on a disk in any drive, and change disks in a drive. The user is 
completely freed from having to know how the operating system 
handles those tasks. 

Before you make calls to the Standard File Operations Tool Set, it 
must be loaded and started up. If you think it may not be needed 
every time the program is run, you can choose to load the tool set 
only when you need to present the dialog boxes. 



The Hodgepodge loutlne 
Open Fitter, listed under "The 
ProDOS File System' in Chapter 6, 
is on example of how an 
application can filter tile types in 
Its Open File dialog box 



Opening a file 

When the user makes a request to open a file, your application 
calls the SFGetFile routine to present the standard Open File 
dialog box (Figure 5-4) and retrieve the filename. SFGetFile allows 
you to specify where the standard dialog box will be placed on 
the screen, to specify the prompt at the top of the box, and to 
select, or filter, the types of files to be displayed in the box. The 
routine does not allow you to modify the appearance of the box; 
if you wish to construct your own custom dialog box, another 
routine is available, 
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.oad which picture: 
© /HODGEPODGE/ 










Q fIMEflM?8 
CD HP.ASM 
CD HP.CC 
CD HP.PflS 
DPICl 


1> 


f Disk 


) 




(f Open 


J 


f £!»** 


) 




D PIC2 




D MflOHt 

n SIMM I 


A 

... 


( Cancel 


) 



Figure 5-4 

The Open File dialog box 






AsftUser is in tne source file 
PAINT.PAS. 



In HodgcPodge, the opening of a file is initiated when the user 
chooses Open from the File menu. That menu choice causes the 
execution of the routine DoOpenltem, which calls openwindow, 
described in Chapter 4, When opening a picture file rather than a 
font window, Openwindow calls AskUser, the routine that uses 
Standard File Operations to select which file to open. AskUser 
looks like this: 



function AskUser: Boolean; 

var ourTypeList: TypeListptr; 

begin 

SFGetFilo ( 






20,20, 

"Load wich picture:', 

@OpenFiltar, 
TypeListRecPtrtOj , 

myReply) ; 



AskUser := FALSE, - 
if my Reply . good then 
if LoadQne then 

AskUser :» TRUE; 
end; 



(begin AskUser...} 

la record that lists file types: 
defined by Std. File Operations} 



{Gall up the dialog box...} 
(upper-left comer = 20,201 

{- message to user} 
(QpenFilter screens file types} 
(NIL ptr — show all file types} 
(place the results here} 

(initialise this function) 
[if SFGetFile not cancelled,.) 
{...and if the file opens OK...} 
jA.sk.User completes successfully} 
(End of AskUser} 
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The complete sequence of 
routines that execute when a file 
Is opened is diagrammed In 
Appendix D. 



DoSaveltem is in (tie source file 
PAiNT.PAS. 



AskUser calls LoadOne, which allocates the memory for and 
actually opens the requested file by making Memory Manager 
and ProDOS 16 calls, SFGetFile calls OpenFilter, a routine that 
controls which types of files are displayed in the dialog box and 
how they are highlighted. LoadOne and OpenFilter are 
described in Chapter 6, under "The ProDOS File System. 1 ' 

Saving a file 

When the user makes a request to save a file, use the SFPutFile 
routine to present the standard Save File dialog box (Figure 5-5). 
SFPutFile allows you to specify where the standard dialog box will 
be placed on the screen, to specify the prompt at the top of the 
box, and to specify the maximum number of characters the user 
may type. Jf you wish to construct your own custom dialog box, 
you use another routine. 



© /HODGEPODGE/ 
Free: 222k out of mt 




C Disk ) 


CD HP.flSM 
CD HP.CC 
CD HP.PflS 

DP [CI 
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£H £ Hew Folder 1 


J ( : , ) 

m ( J 
HI 


Save which picture: fl^_ Save JJ 


™ I cancel ) 



Figure 5-5 

The Save File dialog box 

In HodgePodge, DoSaveltem is executed when the user selects 
Save As from the File menu. CCheckFrontw makes sure that Save 
As is enabled only when a picture window is in front, because only 
picture windows can be saved.) DoSaveltem first calls SFPutFile 
to bring up the standard SaveFile dialog box, and then calls 
SaveOne, which saves the contents of the specified window to disk. 
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roeedure DoSaveltem; 



{begin DoSaveltem...} 



vac theWindow : GrafPortPtr; 
myDataHandle : WindDataH; 
i i Integer; 

login 

theWindow := FrontWlndow ; 

inyDataHandle :■* WindDataH ( 

SatWHofCon (theWindow) ) ; 
SFPutFiio( 

2G, 20, 

'Save which picture:', 

myDataHandle* * .name, 

15, 

rryReply) ; 

if my Reply .good than 
begin 
WaitCuroor; 
SaveOne (irryDataHandle"* .pict) ; 

with iryDataHandle''* do 
begin 
name :- myReply.fileNajrie; 
menuStr:- ConcatC'-', 

myReply . f ileName, 
'\N\ 

IntToString (menuID} , 
' \0 . ' ) ; 
for i :- firstWind to lastWind do 
if WindowList [i] - theWindow then 
Leave; 
SfttMI two (MenuStr, 

FirstWindltemfi) ; 
end; 

SatWTitl* (myDataEandle*' 1 . name, theWindow} ; 
CalcManuSlza (0, Q,WindowsMenuID] ; 
InltCurtor; 
end; 

and; 



(pointer to a window) 

(handle to our window -data record} 



{Get a pointer to the front window) 
(Get a handle to the window-data.,.) 
{...record for the window} 
{Bring up the Save File dialog...} 
{...at location (2 0,20) ...J 
(...with this prompt string-.} 
{„.default = current filename-.} 
{...allow 15 characters in name...} 
(...put answers in Reply record — 
format specified by Std. File} 

[If user doesn't cancel...) 
(Put up the watch cursor and..) 
(...save the file to disk.} 

{Update our window-data record:} 

{Update the window name} 
{MaXe a new menu string.-) 



(Go through the window-pointer list:} 
(If this window is the one...} 
(...exit from this loop} 

{Change menu name to new window) 
(end updating window-data record} 

{Update window name to filename} 
{Resize menu for new window name} 
{go back to arrow cursor} 

{end of IF my Reply. goed=TRUEl 

{End of DoSaveltem} 



The disk writing is done by Ihe routine SaveOne. SaveOne is 
described under "The ProDOS File System" in Chapter 6. 

Don't forget to shut down the Standard File Operations Tool Set 
after you have finished using it — either right afterward, or with the 
other tool sets at application shutdown. If you wish, you can also 
unload the tool set from memory and thus save space. 

♦ Noie: If you choose to unload the Standard File Operations Tool 
Set, be sure to reload it before making its startup call again. 



Communicating with files and devices 



165 



Printing 

The Print Manager is an Apple IIGS tool set that allows you to ! 
standard QuickDraw II routines to print text or graphics. The Pr 
Manager calls a printer driver to do the specific printing tasks, 
your application doesn't need to know what kind of printer is 
connected to the computer. However, the Print Manager also 
includes low-level calls to the printer drivers so that you can 
implement alternate, low- level printing routines. 

An application that supports printing must have three items in it 
File menu: Choose Printer, Page Setup, and Print. Choosing these 
items brings up dialog boxes that allow the user to specify how a 
document will be printed. 

Choosing a printer 

When the user selects the Choose Printer item, the Choose Printer 
dialog box is displayed (Figure 5-6). It lets the user select a 
destination device from among the printer drivers on the system 
disk. The Choose Printer dialog box also lets the user pick which 
port or slot the device is connected to, from among the port 
drivers on the system disk 



Choost Printer vl.2 
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Figure 5-6 

The Choose Printer dialog box 
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DoChooserltem Is In tha source 

file PRINT.PAS. 



If the AppleTalk network is installed and the AppleTalk selection is 
made in the dialog box, the network is scanned for the name. 1 ; of 
all connected printers. If one or more printers of the chosen type 
are available on the network, an additional dialog box appears so 
ihat the user can select one. 

•J" Macintosh programmers: On the Apple lies, the Choose 
Printer function is part of the Print Manager, rather than part 
Of the Chooser desk accessory as on the Macintosh. 

The HodgePodge routine that brings up the Choose Printer 
dialog box is called DoChooserltem. It is called from DoMenu, 
when the user selects Choose Printer from the File menu. 



procedure DoCheoserltern; 

var dmrmy: Boolean; 

begin 

dummy := Pr Choose r; 
and,- 



( begin DoChooserltem..] 

(returned value is unimportant here} 



{Bring up dialog box — that's iti) 
{End of DoChooserltem} 



Making page settings 

When the user selects the Page Setup item, a Style dialog box is 
displayed (Figure 5-7), It allows the user to specify formatting 
information, such as the page size and printing orientation. This 
information is not changed frequently and is usually saved with 
the document. The LaserWriter offers two style options 
unavailable for the ImageWriter: smoothing of bitmapped fonts, 
^>nd font substitution. 
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IHBCEWRITEfl/BPPLETULK vl,3 
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Vertical Sizing: Printer Effects: 
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( Cancel] flit 



DoSetupltem Is in the source file 
PRINT.PAS. 
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Enlarge: 
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Figure 5-7 

Style dia fog boxes 

Page setup in Hodgepodge is handled by the routine 
DoSetupltem, called from DoMenu when the user selects Page 
Setup from the File menu. DoSetupltem calls the Hrint Manager 
routine PrSLlDialog, passing it a handle to a prim record. The 
print record has been allocated and initialized by the routine 
Set UpDe fault, called at startup. 
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_ 

rar dummy: Boolean; 



begin 
dummy 

end; 



PrStl Dialog (printHndl } 



(begin DoSetOpItem...} 

(function result unimportant here} 



(Call up the dialenj, pa as it the 
handle to our print record) 
(End of Do&atuprtem) 



Printing 

When the user chooses to print a document, usually by making a 
selection on the File menu, the Job dialog box is displayed (Figure 
5-8). The Job dialog box lets the user select print quality, page 
range, number of copies, and other printer-specific information, 
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Figure 5-fl 

Job dialog boxes 
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DoPrintltem Is In the source file 
PR INT. PAS. 



procedure DoPr intltem; 

var prPort : GrafPortPtr,- 

theWindow: GrafPortPtr,- 



The Print Manager automatically gives you a QuickDraw II 
GrafPort when you open a document for printing. You then print 
text and graphics by drawing into this port with QuickDraw i\ calls 
just as if you were drawing on the screen. The Print Manager 
installs its own versions of QuickDraw IPs low-level drawing 
routines in this GrafPort, causing your higher level QuickDraw II 
calls to drive the printer instead of drawing on the screen. 

The HodgePodge routine that prints files is DoPr intltem, cal 
from DoMenu when the user selects Print from the File menu. 
DoPrintltem calls the routine PrJobDialog to bring up the Job 
dialog box, and then calls DrawTopWindow to print the file; 

{begin DoPrintltem...) 



begin 

theWindow : = FrontWindow ; 
if theWindow o NIL then 

if PrJobDlalog (printHndl } then 
begin 

Wait Cursor,' 
prPort := ErOpanDoa (printHndl, NIL), ■ 

PrOpAnSaga (prPort, NIL) ; 
DrawTopWindow (theWindow) ; 
PrCloaepaga (prPort) ; 

PrCloaaDoe (prPort) ; 
PrEicFila (printHndl , NIL, NIL) ; 
In it Cu r a or ," 
end; 

end/ 



(pointer to a printing GrafPort J 
f win daw pointer) 



{Get a pointer to the front window} 
(If there IS a window open...} 

{-.bring up the dialog box; if,.,} 
{-..the user doesn't cancel...) 
(put up the watch cursor..} 
{open a printing GrafPort...} 

(begin a new {£ only} page...} 
{draw the contents of the page„.) 
{...cloge the page} 

{...close the GrafPort) 

(...print the spooled file) 

{...and restore the regular cursor) 

{end of printing} 

(end of IF a window is open) 

{End of DoPrintltem) 



DrawTopWIndow is In the source 

file PRIMT.PAS. 



See "Using the Print Manager," later in this section, For 
explanations of some of the Print Manager calls that 
DoPrintltem makes. 

DoPrintltem calls the subroutine Dr a wTop window, which does 
the actual drawing in the printer GrafPort. DrawTopWindow acts 
no differently than if it were drawing to the screen; it calls cither 
ShowFont or Paintlt, depending on what type of window is to 
be printed: 
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procedure DrawTQpWindow{TheWindow:WindowPtr} ,- 

var myDataHandle : WindDataH; 

.begin 

myDataHandle := WindDataH ( 

GtftWRafCon (TheWindow) ) ; 

with myDataHandle*" do 
if Flag - che/i 

Paintlttpict) 
else 

Show Font {theFont, isMono) ; 
end; 



(begin DrawTopWindow...} 

{handle to window-data record} 



(Get a handle to the window's,., 
[...window-data record} 



{If it's a picture window...} 
{paint the picture w/this handle} 
[But if it '3 a font window,,,} 
[draw text w/thia font & style} 

(End of DrawTopWindow} 



The structure of o print record Is 
Ihown In the Appta SIGS Toolbox 
Reference 



Using the Print Manager 

Print records: Before you can print a document, you need a valid 
print record. The print record describes information such as page 
dimensions and resolution. You can either use an existing print 
record (for instance, one saved with a document) or create one 
through Print Manager calls. HodgePodge uses the same print 
record for all documents, That record can be modified by the 
user through the Style and Job dialog boxes. 

* Note: Whenever your application saves a document, it should 
save an appropriate print record with the document. This sets 
up the printing parameters for the document so that they can 
be used the next time the document is printed. 



Important In most Instances your application should not directly change the 
data In the print record— it should use the standard dialog routines 
for changing this Information. Attempting to set certain values 
directly in the print record can produce unexpected results. 

Draft and spool printing: There are two basic methods of 
printing documents: draft and spool. 

In draft printing, your QuickDraw 11 calls are converted directly 
into command codes the printer understands, which are then 
immediately used to drive the printer. The LaserWriter always uses 
draft printing, because the QuickDraw II calls are translated 
immediately into PostScript commands. The I mage Writer and 
other nonintelligent dot matrix printers are written to in draft 
mode for text only High-quality pixel images are produced by 
spool printing. 
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Compare ftiis sequence of calls 
with the listing of the HodgePodge 
routine PrawTopWindow, earlier 
In this section. 



In spool printing the Print Manager processes your printing 
requests in two steps. First it writes out (spools) a representation of 
your document's printed image to a disk file or to memory. 
Second, this informalion is converted into a bit image and 
printed. This method is used to print graphics on the 

1 mage Writer. 

The printing loop: To print a document, you call the following 
routines: 

1. PrOpcnDoc, which returns a pointer to the GrafPort to be ui 
for printing 

2 PrOpenPage, which starts each new page (reinitializing the 
GrafPort) 

3. QuickDraw routines, for drawing the page into the port create 
by PrOpcnDoc 

4. PrClosePage, which terminates the page 

5. PrCloseDoe, at the end of the entire document, to close the 
GrafPort being used for printing 

6. PrPicFile, to print the spooled document 

Steps 2 through 4 are the printing loop itself; they are repeated for 
as many pages as are printed. Each page is either printed 
immediately (draft printing) or written to disk or to memory 
(spool printing). Your application may inspect the print record to 
see whether spooling was done, but it doesn't have to. The proper 
method is always selected automatically, and PrPicFile is execul^ 
only if needed. 

You should check for errors after each Print Manager call. If an • 
error occurs and you cancel printing (or if the user aborts 
printing), be sure to exit properly from the printing loop so Lhati 
all files are dosed correctly — that is, be sure that every 
PrOpcnPage is matched by a PrClosePage, PrOpcnDoc is 
matched by PrCloseDoe, and PrPicFile is still called. 

<• Note: The maximum number of pages in a spool file is 16,382^ 
If, for some strange reason, you need to print more than Ifj,3 
pages at one time, just repeat the printing loop. 
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Transfer modes ar9 discussed 

under 'Drawing to the Screen." 
Chapter 3. 



"i 



QuickDraw II consequences and I imitations: Even though you 
print by making QuickDraw calls, remember thai printing to paper 
is not really the same as drawing to the screen. Clipping regions 
and character spacings don't translate exactly. Erasing, of course, 
can't be done on a printer. Some transfer modes and some 
drawing routines don't work on a LaserWriter. For more 
information about optimizing your printing code, see the Apple 
HGS Toolbox Reference and the LaserWriter Reference. 

Background procedure: An optional background procedure 
runs whenever the Print Manager has directed output to the 
printer and is waiting for the primer to finish. It is typically a 
dialog box that informs the user that a print job is in progress, 
and allows the user the option of canceling it. 

If you don't designate a background procedure, the Print Manager 
uses a default procedure for canceling printing: the default 
procedure just polls the keyboard and sets a Print Manager error 
code if the user presses Apple-Period. If you use this option, you 
should display a dialog box during printing to inform the user 
that the Apple-Period option is available. 



The multiple-segment sample 
program listed under "Creating 
Segmented Code: Three 
Examples " in Chapter 7 Includes 
calls to the Text Tool Set. 



The Pascal and BASIC character 
device drivers are discussed In 
me Apple 1SGS Fkmwate 
fleference 



Sending text to Apple II character devices 

If you are writing a native-mode Apple IIGS application but don't 
want to use QuickDraw II and the graphic desktop interface, you 
may need the Text Tool Set. It provides an interface between 
Apple 11 character device drivers, which must be executed in 
emulation mode, and new applications running in native mode. It 
also provides a means of redirecting I/O through RAM-based 
drivers. The Text Tool Set makes it possible to deal with the text 
screen without switching 65816 processor modes and moving to 
bank zero. Dispatches to RAM-based drivers still occur in full 
native mode. 

The Text Tool Set has global routines that are used to set or read 
the current global parameters used by RAM and the Pascal and 
BASIC text drivers. 'Itie tool set also has I/O directing routines 
that direct I/O from the tool set to a specific type of character 
device driver, or request information about the directing of a 
specific I/O driver. Finally, the tool set has text routines that 
interface with any BASIC, Pascal 1.1, or RAM-based character 
device driver. See "Text Tool Set" in the Apple lies Toolbox 
Reference for more details. 
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Communicating with Apple Desktop Bus devices 

The Apple Desktop Bus CADB) is a hardware channel and a 
protocol for connecting input devices, such as keyboards and 
mouse devices, with personal computers. The personal computer 
is considered to be the host during the communication, and 
controls the communication on the bus by issuing ADB 
commands to the devices, 

The Apple Desktop Bus Tool Set sends commands and data 
between the Apple Desktop Bus microcontroller and the rest of 
the system. Typically, the tool set is used to control ADB activity, 
but other commands, which are used by diagnostic routines and 
the Control Panel, are available. 

Most applications have no need to use the ADB Tool Set 
However, if your program needs 10 modify the system's interface 
with the mouse, keyboard, or other ADB device, the ADB Tool Set 
is indispensable. 

More details about the bus can be found in the Apple IIGS 
Firmware Reference and the Apple HGS Hardware Reference. The 
tool set is described under "Apple Desktop Bus Tool Set" in the 
Apple HGS Toolbox Reference. 



Making sounds 

The Apple IIGS has a very advanced sound-generation system, 
capable of creating and reproducing complex music, sound 
effects, and speech, Sound tools at several levels give you access 
to the sound hardware and make music generation easy. 



The sound hardware 



The Apple IIGS sound hardware supports two sound-generation 
methods. In the first method, which replicates the Apple He sound 
capabilities, an application toggles a soft switch which in turn 
generates clicks in a speaker, The application can control the rate 
of clicking and the volume of the speaker. 
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The second method uses a digital oscillator chip (DOO and the 
rest of the sound hardware, as diagrammed In Figure 5-9: 64K of 
dedicated RAM, the Sound GLU (general logic unit), the analog 
section, and the sound connector. 
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Figure 5-9 

Sound hardware block diagram 

The sound GLU acts as the I/O interface between the Apple IIGS 
system hardware and the sound hardware. The dedicated RAM 
stores the waveforms used for sound generation. From them the 
DOC can create sounds of practically any pitch and duration. 

The analog section contains all the circuitry needed lo amplify 
and niter the signal coming from the Sound GLU or the DOC. 
From there the signal is sent to the speaker. 

The sound connector provides the connection to interface cards 
that can take the tones generated by the DOC and modify them 
farther. Three examples of possible sound cards are 
programmable filter cards, stereo interface cards, and sound 
sampling cards. 

Oscillators and generators 

An oscillator is the basic sound-generating unit in the DOC, The 
DOC contains 32 oscillators, each of which can function 
independently from all the other oscillators. 
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The System Failure Manage; Is 
described under •Miscellaneous 
Tool Sef " In the Apple ms 
Toolbox Reference. 



See "Sound Tool Set* In the 
Apple lies Toolbox Referencefor 

details on both high-level (free- 
form synthesizer) and low-level 
calls. 



One of the modes of the DOC is called swap mode. The Sound 
Too! Set (described next) uses this mode to generate sounds In 
swap mode, a pair (snap pair) of oscillators forms a functional 
un.t called a generator. There are 15 generators denned in the 
Apple 1ICS sound system. The oscillators in a generator take turns 
makrng sound, each signaling the end of its sound by generating 
an interrupt. 

Oscillators 30 and 31 are reserved for system use and should not 
be be used by applications. If an interrupt is generated by 
oscillator 30 or 31 it is a fatal error— a sound interrupt is reported 
to the System Failure Manager, which halts execution, 



The Sound Tool Set 

The Sound Tool Set gives you the ability to access the sound 
hardware without having to know specific hardware I/O addresses 
Sound Tool Set calls can be divided into two groups high-level 
and low-level. 



High-level calls constitute the free-form synthesizer. Calls to the 
free-form synthesizer are made through the normal tool call 
mechanism, with parameters being passed to and from the called 
routines on the stack. With high-level calls you can 

□ write multibyte sound data to and read it from DOC RAM 

□ get or set the volume of individual generators 

□ start and stop sound on an individual generator 

Low-level routines read from and write to the DOC hardware 
regjsters and individual DOC RAM locaiions. Unlike the other 
Sound Tool Set routines, which use the stack to pass parameters in 
the normal tool call fashion, these routines use registers to pass 
parameters and are entered through a jump table. The low-level 
rouunes can move information faster than the higher-level calls 
to the free-rorm synthesizer, but they do none of the error 
checking and housekeeping of the higher-level routines 
Furthermore, if you use the low-level routines, you will have to 
install your own interrupt handler to service sound interrupts 
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The Note Synthesizer 

The Note Synthesizer gives your application a convenient way to 
play musical notes. You use the Note Synthesizer by making tool 
calls to start and stop individual notes. The general sequence of 
calls is something like this: 

1. Allocate an individual generator. 

2 Start a note, with the NoteOn call. The call's parameters specify 
the generator to play the note on, the note's volume and pitch, 
and what instrument to use. An instrument is a data structure 
that specifies such parameters as the amplitude envelope 
(attack and decay shapes), pltchbend and vibrato 
characteristics, and the specific waveforms that characterize the 
sound to be played. 

3, Stop the note with the NoteOJT call- When the note stops 
playing, the generator is automatically deallocated. 

The Note Synthesizer provides for priority in allocation of 
individual generators. If all generators are in use, generators 
producing low-priority sound (such as notes trailing ofQ can be 
"stolen" to produce higher- priority sounds {such as notes starting 
up). Priority assignment can assure that there will always be a 
generator available when a note needs to be played, 

♦ Enable interrupts: Interrupts must be enabled in order for the 
Note Synthesizer to function. Anything that disables interrupts 
(such as accessing a disk drive) will disrupt the sound being 
played. 



The Note Sequencer 

The Note Sequencer is the tool set that makes it easy for you to 
include music in your programs. In particular, it allows music to 
be played asynchronously, in the background. 

The Note Sequencer builds upon the Note Synthesizer, in that it 
strings together individual notes created by the sythesizer. 

You can think of the Note Sequencer as a cross between a player 
piano and a language interpreter. A sequence is a series of 
commands that tell the computer which notes to play and when. 
The Note Sequencer plays back that sequence to generate muscial 
sound. 
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MIDI stands tor Musical Instrument 
Digital interface, on international 
standard for electronic transfer of 
musical data. 



Sequences are built up from simpler components. Individual 
commands to the Sequencer are called items. Items typically tun 
a note on or off, or control some aspect of the note's sound, sud 
as vibrato. Items arc assigned to one or more tracks, to facilitate 
the concept of multi-instrument music and chords, A pattern is J 
series of items; the pattern groups those items in terms of their 
mutual timing relationships. 

A phrase is a set of pointers to patterns or to other phrases. 
Phrases make it easy to build repetitive, complex passages cut i 
simple patterns. A sequence is a top-level phrase, one which 
points to patterns or other phrases but is not pointed to by 
other phrases, 

You play music with the Sequencer by making a StartSeq calf . 
plays a specified sequence. In interrupt mode, the sequence is 
played automatically until it finishes. In step mode, your 
application can play the sequence item-by-item. Step mode is 
useful if you need to synchronize the sequence with other events 
in your program 

<• Enable interrupts: Interrupts must be enabled in order for the 
Sequencer to function. Anything that disables interrupts (such 
as accessing a disk drive) will disrupt the sound being played. 

* MIDI- The Sequencer is not direcdy compatible with the MIDI 
protocol, If you wish 10 communicate with a MIDI synthesizer 
on your Apple JIGS, you will need to install a MIDI interface 
card or a MIDI serial adapter (manufactured for the Macintosh 
Plus), At the time of this writing, there are no software tools to 
allow the Note Synthesizer or Sequencer to manipulate MIDI 
data, 



Computing 

If your applications require mathematical computations on either 
integers or floating-point numbers, there are Apple IIGs tool sets ^ 
that provide you with fast, consistent, and accurate algorithms. 
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Integer Moth 

The Integer Math Tool Set supports multiplication and division of 
several types of numbers, and also converts numbers from one 
type to another. The types of numbers dealt with are these: 

integer lfj-bit signed or unsigned value 

longint 32-bit signed or unsigned value 

fixed 32-bit signed value with 16 bits of fraction 

frae 32-bit signed value with 30 bits of fraction 

extended 80-bit signed value with 64 bits of fraction 

♦ Note: The extended type really serves as a pathway to the 
Standard Apple Numeric Environment. See the next section in 
this chapter, "High-Precision Floating-Point Math (SANE)." 

The Integer Math Tool Set also manipulates Integer Math strings, 
which are ASCII-string representations of numbers. An Integer 
Math siring consists of only digits (hexadecimal or decimal) and 
blanks and has no lengih byte within it 

Within the tool set, there are math routines and Integer Math 
string routines. Math routines support multiplication and division 
of integer, long integer, fixed, and frac numbers, perform simple 
trigonometric calculations, and convert from one type of value to 
another. Integer Math string routines convert between a binary 
value and an ASCII character string representing that value. The 
binary value can be either an integer or a long integer. The 
character string can be in either hexadecimal or decimal format. 

Your application can make use of the Integer Math routines at any 
time: the tool set is always active. Furthermore, the Integer Math 
Tool Set does not rely upon the presence of any other tool sets. 



High -precision floating-point math (SANE) 

For high-precision calculations on floating-point numbers, your 
application should use the Standard Apple Numerics 
Environment (SANE). SANE is a collection of routines that 
perform extended-precision IEEE arithmetic, with elementary 
functions. SANE scrupulously conforms Eo IEEE standard 754 for 
binary floating-point arithmetic and to the proposed IEEE 
standard 854, which is a radix-independent and word-length- 
independent standard for floating-point arithmetic. 
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Additional information on SANE 
routines Is found under "SANE 
Tool Set" In the Apple (IG$ 
Toolbox reference 






SANE provides sufficient numeric support for most application! 
includes 

□ IEEE types single 02-bit), double (64-bit), and extended (80- 
bit) 

□ a 64-bit type for large-integer computations, as in accounting 

□ fundamental floating-point operations ( + - * / V rem ) 
D comparisions 

□ binary-to-decimal and floating-poinMo-intcger conversions 

□ scanning and formatting for ASCII numeric strings 

□ logarithm ics r trigonometries, and exponentials 

P compound and annuity functions for financial computations 

□ a random number generator 

D functions for management of the floating-point environment: 

□ other functions required or recommended by the IEEE 
Standard 






The Apple IIGS SANE tool set matches the functions of the 
Macintosh SANE packages, and the 6502 assembly-language SAN 
software from which it is derived. 

The functions of SANE are completely documented in the Appb 
Numerics Manual, which you will need if you are going to use th 
routines in your application. 






Controlling the operating environment 

Many components make up the Apple TIGS operating 
environment, the overall hardware and software setting within 
which application programs run. Several tool sets' principal 
functions are to control and modify that environment. You mig 
call them low-level tool sets, in contrast to the higher-level, 
desktop interface tools. 

The Event Manager, described earlier, and the Memory Manag, 
and System Loader, described in the next chapter, are three of I 
most important tool sets in this group. Two others are the 
Miscellaneous Tool Set and the Scheduler, described here 
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The Miscellaneous Tool Set 

The Miscellaneous Tool Set is a collection of several small tool 
sets. Most of them set or return information about various low- 
level functions of the Apple IlCS. Several other managers and tool 
sets make calls to the Miscellaneous Tool Set. 

Many of the routines in this tool set retrieve the address or return 
the value of a given parameter so that your program need not rely 
on fixed addresses. Please use these calls instead of directly 
accessing memory locations; there is no guarantee that an address 
being used for something in one version of system software will 
be used the same way in subsequent versions. 



Parameter RAM. also known as 
Battery RAM. retains clock- 
calendar and Control Panel 
Wor motion when the computer 
power Is off, 



tick count is fappfoximareiy) the 
number of aOth-secand Intervals 
elapsed sines system startup. 

For more information about 
interrupt sources and handlers. 
$bb the Apple Mss Firm ware 
Reference and (fie AppleIGS 

ProDOS \6 Reference. 



Groups of routines 

a You can use Battery RAM routines to write and read data to 
and from parameter RAM. Any data written to parameter 
RAM will affect the default system configuration, which will be 
used the next lime the system is booted. 

□ The clock routines provide you with a way to read the current 
lime either in hex or ASCII format, or set the current lime using 
hex format. The GetTick routine reads the current tick count, 

□ Vector routines set or return the vector address for a specified 
interrupt manager or handler. Interrupt control routines allow 
your application to enable or disable certain interrupt sources 
and get the current status of those interrupts, 

D Address and entry routines return ihe addresses and native- 
mode entry points of some important firmware parameters and 
routines. 

□ The HeartBeat routines allow you to install or delete tasks from 
the HeartBeat Interrupt Task queue. Such tasks might include 
controlling cursor movement, or posting a disk-insert event, or 
checking the stack. They are called at some multiple of every 
"heartbeat" (vertical blanking interval), 60 limes a second. 

□ The System Failure Manager routine allows you to customize 
the system failure message. Thus, if the user causes your 
application 10 crash, you can have the Syslem Failure Manager 
display a message that gives the user an idea of what happened. 



Controlling the operating environment 
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□ The User ID Manager routines create and delete the numbers 
by which the ownership of all allocated memory blocks is 
specified. Every program on die Apple IIGS has a User ID, 
assigned by the User ID Manager; each block that the Memory 
Manager allocates for that program is given the program's 
User ID, 

d The mouse routines allow your application to direcdy set or g* 
the mouse location. However, the Event Manager calls these 
routines automatically, so most applications don't need to 
make the calls. If you're not using the Event Manager or 
TaskMaster, you may need to use the mouse routines. 

□ The PackBytcs routine packs data to make a file smaller. This 
can be useful for such things as graphic images, which would 
ordinarily take up too much space on disk. UnPackEytes 
unpacks the data from the PackBytes format. 

□ The Munger routine allows your application to manipulate 
Strings easily. 

a The SysBeep routine causes the system speaker to beep. 

"The Miscellaneous Tool Set" in the Apple IIGS Toolbox 
Reference describes in detail all of the above groups of routines. 



The Scheduler 

The Scheduler is a tool set that delays the activation of a desk 
accessory or other task until the resources that the desk accessory 
or task needs become available. Much of the system code is not 
reentrant; that is, the code cannot be called again while it is 
executing. Because of that, activating a desk accessory within non- 
reentrant code almost always causes the system to fail. Thus, the 
Apple IIGS provides a Busy flag that the Scheduler can check to 
discover if a needed resource is busy or available. 

To write a typical application, you won't need to use the 
Scheduler. Even ir you are writing a classic desk acccessory you 
won't need to call the Scheduler— the Desk Manager does it for 
you, Perhaps the only time you need to use it is when you are 
writing interrupt handlers that access FroDOS 16 or the toolbox 
routines. For example, an application that performs background 
printing might need to access the Scheduler. 
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lha Scheduler Is completely Scheduler maintains a queue of tasks waiting to execute, and 

documented under "The consults the Busy flag before dispatching them. "When a non- 

Sff^feSnce^ "° S reentrant module is entered, your interrupt handler should set the 

Busy flag; when exiting from the module, the application should 
clear the Busy flag, permitting the Scheduler to execute any tasks 
that have been placed in its queue. 

Your interrupt handler should therefore check the state of the 
Busy flag before it calls any system software. If the word is 
nonzero, the necessary system resources are not currently 
available, and you should add your task to the Scheduler's queue. 
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For a complete description of 
Memory Manoger functions, see 
"Memory Manager" In the Apple 
lies Toolbox Reference 



What the Memory Manager does 

The Memory Manager is a ROM-resident Apple IIGS tool set that 
controls the allocation, deallocation, and repositioning of 
memory blocks in the Apple ncS. The Memory Manager works 
closely with ProDOS lo and the System Loader to provide the 
needed memory spaces for loading programs and data and for 
providing I/O buffers. All Apple IIGS software, including the 
System Loader and ProDOS 16, must obtain needed memory 
space by making calls to the Memory Manager, 

The Memory Manager keeps track of how much memory is free 
and what parts are allocated to whom. Memory is allocated in 
blocks of arbitrary length; each block possesses several attributes 
that describe how the Memory Manager may modify it (such as 
moving it or deleting it), and how it must be aligned in memory 
(for example, on a page boundary). Table 6-1 describes the 
memory block attributes and lists the predefined constants with 
which each can be specified. 



Table 6-1 

Memory block attributes 



Attribute 



Constant" 



Explanation 



Fixed (yes/no) 



Fixed address (yes/no) attrAddr 

Fixed bank Cyes/no) attrBank 

Bank-boundary limited (yes/no) attrNoCross 

Special memory not usable (yes /no) attrNoSpec 



Page-aligned (yes/no) 
Purge level CO to 3) 

Locked (yes/no) 

' Equivalent to "yes" if present 



attrFixed Must the block remain at the same location 

in memory? 

Must it be at a specific address? 

Must it be in a particular memory bank? 

Is it prohibited from extending across a 
bank boundary? 

Is it prohibited from residing in banks SOO, 
$01, and parts of banks $E0, $E1? 

attrPage Must it be aligned to a page boundary? 

attrPurge Can it be purged (made available for other 

use)? If so, with what priority? 

attr Locked Is the block locked (temporarily fixed and 

unpurgeable)? 



The Memory Manager Is In charge! 
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The System Loader Is described 

under "Loading Programs and 
Segments,* later In this chapter. 



3 



♦ HodgePodge. For an example of the use of pre denned 

constants (column 2 of Table 6-1) in specifying memory-block 
attributes, see any of HodgePodge's NewHandle calls— such as 
in the routine StartUpTools (Chapter 2), See also "How Your 
Application Obtains Memory," later in this section. 

Memory-block attributes are specified in an attributes word. 
When you request a block of memory, you supply the attributes 
word for that block. Later, you can modify the value of the 
attributes word to change the block's characteristics. 

In addition to creating and deleting memory blocks, the Memory 
Manager moves blocks when necessary to consolidate free 
memory and relieve memory fragmentation. When it compacts 
memory in this way (Figure 6-1), the Memory Manager can move 
only those blocks that needn't be fixed in location. Therefore as 
many memory blocks as possible should be movable (not fixed), 
if the Memory Manager is to be efficient in compaction. Data 
segments and segments containing position-Independent code 
can generally be placed in movable blocks. 



Before compaction 



After compaction 



Fixed blocks Movable blocks Ree memory 

Figure 6-1 

Memory fragmentation and compaction 
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Pointers and handles to memory blocks 









To access an entry point in a movable block, an application can- 
not use a simple pointer, because the Memory Manager may move 
the block and change the entry point's address. Instead, each time 
the Memory Manager allocates a memory block, it returns to the 
requesting application a handle referencing that block. 

A handle is a pointer to a pointer: it is the address ol a fixed (non- 
movable) location that contains the address of the block. If the 
Memory Manager changes the location of the block, it updates the 
address in the fixed location; the value of the handle itself is not 
changed. Thus the application may continue to access the block by 
using the handle, no matter how often the block itself is moved in 
memory. 



Memory block 



a. Pointer: 

Value of pointer = 

starting address of memory block 



SXXX 



sxxx 




Memory block 



t>. Handle: 

Value of handle = 
oddress of master pointer 



SXXX 




szzz 



'S2Z2 



Master pointer 



SXXX 



Figure 6-2 

Pointer and handle 



If a block will always be in the same place in memory (that is 
either locked or fixed), it may be referenced by a pointer instead 
or by its handle. To obtain a pointer to a particular block or 
location, an application can dereference the block's handle. The 
application reads the address stored in the location pointed to by 
the handle — that address is the pointer to the block. Of course, if 
the block is ever moved that pointer is no longer valid 



The Memory Manager is In charge! 



In most high-level languages, dereferencing is a simple, single- 
statement task. For example, in C the statement 



Decef 



START 




sta 







stst 


2 




ldy 


14 




Ida 


[o: 


- y 


ora 


#SB000 


sta 


(0] 


y 


dey 






dey 






Ida 


[0] 


y 


tax 






IdaJOJ 




rts 






END 







dereferences the memory handle y. The variable z now o 
a pointer to the memory block whose handle is y. In assembly™ 
language it takes a few more statements; the HodgePodge routine 
Deref On the file GLQBALS . ASM) looks like this: 



store low word of handle at ?ero-page address 
stare high word of handle at ^ero-page address 2 

put the value "4" in V register 

set the.,. 

...attributes bit that... 

-locks the block 

now Y=3 

now Y=2 

put high word of pointer into acumulator 

put high word of pointer in X register 

put low word of pointer in accumulator 

return to caller 



A memory handle that points to o 
value of zero Is called NIL 



When a memory block is purged, the memory that its handle 
pointed to becomes available for other use but the handle itself 
remains in memory. A purged memory handle points to the 
address $00 0000, but retains its User ID and all its attributes as 
listed in Table 6-1, so that the memory block can be quickly and 
easily reallocated if necessary. 

When all the attributes of a memory handle as well as the 
memory it points to are discarded, the handle is said to be 
disposed, A disposed memory handle is no longer associated wild 
a particular program. Your application can get rid of memory it j 
no longer needs by making a DisposeHandle call. 

Pointers and handles must be at least 3 bytes long to access the 
full range of Apple IIGS memory. However, pointers and handles 
passed as parameters are always 4 bytes long, because they are 
then easier to manipulate in Lhe 16-bit registers of the 65C816 
microprocessor. 



Important 



Do not us© the high-order byte of a 4-byte pointer or handle to 
store data. The unused byte b reserved for system use-your 
application should always fill It with zeros, 
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How your application obtains memory 

When an application makes a call to the operating system or 
other system software that requires allocation of memory (such as 
opening a file or writing from a file to a memory location), the 
system software first obtains any needed memory blocks from the 
Memory Manager and then performs its tasks. When an 
application informs the operating system that it no longer needs 
that memory, the information is passed on to the Memory 
Manager which in turn frees that application's allocated memory. 
In these cases the memory allocation and deallocation is 
completely automatic, as far as the application is concerned. 



Requesting memory 

Any other memory that an application needs for its own purposes 
must be requested directly from the Memory Manager. The 
shaded areas in Figure 6-3 represent those parts of the Apple IIGS 
memory that can be allocated through requests to the Memory 
Manager. Apple 1ICS applications should avoid requesting 
absolute (fixed-address) blocks — it defeats the Memory Manager's 
ability to allocate memory as efficiently as possible, and increases 
the probability that the program will not be able to load or run. 



SFFFF— 
SE0O0- 

SDogo- 
scooo- 



r 

S00 SOI $02 



■ Bank numbers - 



50800- 




SEO SE1 



$2000 



Figure 6-3 

Memory allocatabla through the Memory Manager 



The Memory Manager Is fn charge! 
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Youi ^PPjIcation request memory with the Memory Manager's 
ISewHandle call. Here is an example from HodgePodge: 



tooiazeroPaije 



t- NewHandle(TotaiDP, 

my Memory ID, 



Direct-page space is described 

In mora data if later in this chapter. 



attrBank+attrFixed+attrLacked+attrPaae 
PtrtO)); 9 ' 

In this example HodgePodge is requesting direct-page space for 
tool set use. ToolsZ«oPag* is a handle to the requested space 
Inputs to the call are: size CTotalDP). User ID (myMemoryiD) 
predefined constants specifying attributes (as described in Table 
b-l) and a po.mcr to where the block is to begin (bank $00 in I 



Tne User id Manager Is dasaibed 

under "Miscellaneous Tool Set* 
m the Apple Hgs Toolbox 
Reference 



User IDs 

Many Memory Manager calls use the block's User ID a code 
number that shows what program owns the memory block L'ser 
IDs are assigned by the User ID Manager. 

When your application starts up the Memory Manager the 
operating system has already assigned a master User m for that 
execui.on of the application. The operating system gives the 

oa^s , a r,n D , nUmbef '° ; he MemDfy M ">»*--. "Li in turn 
passes that ID to your application in the MMStanUp call You 

must save that ID for use when you shut down your appIieatSl 



Bit: 
Value: 



Byte 1 



15 I 14 13 



12 | 1 1 ,10 



typelD 



auxlD 



Byte 



6 , 5 



main ID 



Figure 6-4 
User ID format 

Z F Jm* 6 -f" h °^ Uscr IDs a 'e mwte up of three fields-the 
typelD, auxlD. and mainID fields-contained in a word-length 
parameter The value in the malnJD field is assigned by the Userl 
Manager. The typelD field contains a number that describes tTe 
genera kmd of program segment that wili occupy the biX-such 
as application, desk accessory, or tool set The au^ID field I 

value .s 0; your application can store any 4-bit value there 
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Using the auxID field, your application can create up to 15 new 
and distinct User IDs from the single master User ID returned by 
the Memory Manager at startup. You can use each new User ID to 
allocate as many additional, private memory blocks as needed; 
when finished with the memory allocated under a particular lD r 
discard it all at once by calling DisposeAll with that ID. An 
example of this technique is shown in the following assembly- 
language code fragment, 

pusfrword #0 ; space for master User ID 

_MM5tartUp 

pia ,- retrieve master User ID 

sta MasterlD ; store master User ID 

ora #50100 ; create User ID with AOX IP - 1 

sta MylD ; store ID for use w/ private memory 

. . . 

... ; (your code here) 

. - . 

... ; (ready to exit program) 
pushword MylD 

DisposeAll ; discard all of my private memory 

... ; (continue with termination 

... ; processing} 



Important Do not specify an auxID of 0, The Memory Manager routines 

PurgeAll and DisposeAll treat an auxID field with In It as a wildcard 
that matches alt values. 

The main advantage of this method is that you can dispose of all 
allocated blocks quickly and easily, with a DisposeAll call, instead 
of making sure to keep track of all allocated blocks and 
deallocating them individually, 

You don't have to use this method You could simply use the 
master User ID, unchanged, to obtain new private memory. 
However, your application could not then use the DisposeAll call 
to discard everything— it would be disposing of itself too. Another 
method is to obtain an entirely new User ID for private memory. 
This method allows you to discard all private memory at once, 
but leaves open the possibility of allocated blocks remaining in 
memory after your application quits. 

♦ HodgePodge.- HodgePodge makes very few memory- allocation 
requests. It uses an unmodified master User ID when it does so, 
and it makes sure 10 dispose of its requested memory blocks 
individually. 

The Memory Manager Is In charge! 1 93 



Important 



For more Information on memory 
management, see the Apple hgs 
Toolbox Reference and the 
Apple IIGSPraDOS 16 Reference. 

Important 



Locking and unlocking, purging and disposing 

If you need to access a movable memory block directly— that is i 
you need to dereference its handle-^you must first lock it so tha". 
ft won E move while you are using it. When you no longer need it 
to be locked, make sure to unlock it so the Memory Manager can 
move it during compaction. Don 1 ! lock blocks that you are not 
currently accessing. 

If you are temporarily through using a block, and don't mind if ij 
contents must be reconstructed the next time thev are needed 
you can set the block's purge level to make it purgeable Then'i 
Memory Manager can purge it if more space is needed If the 
Memory Manager does purge a Mock, you can quickly restore it 
with the same attributes. User ID, and size. 



When the Memory Manager purges a block, all data in it Is lost Vc 
appllcaton Is responsible for saving and restoring the data 

appropriately, " 



When your application is completely finished with its own privat* 
memory it should dispose of it-far example, by calling the 
DiSposeA I routine and specifying the User ID with a modified 
auxID field, as described earlier. If your application doesn't 
dispose of all memory that it has acquired, the memory 
management system can become clogged. 



Do not call DisposeAII with the unmodified master User ID for your 
own program (the one In which auxlD = 0). V 



The System Loader Is described 

In tha next section of this chapter. 



Load segments and memory blocks 

In Chapter 1 we introduced the idea of segmented programs The' 
execu.be versions of program files are called loadVs, 2 
cons lsl of one or more load segments. Load segments are 

woS ? c.L7 Cm 7 u" ? SyStem L ° ader - The S ^ e * Lt >^ m J 
*ork closely with the Memory Manager because different types S 

segments require memory blocks with different attributes. 
When the System Loader loads a program segment, it calls the 
Me mory Manager to allocate a memory block for the segment 

the attributes of the segment that will inhabit the block 
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If the program segment is static, and therefore must not be 
unloaded or moved, its memory block is marked as unpurgeable 
and fixed. That means that the Memory Manager cannot change 
that segment's position or contents as long as the program is 
running. If the program segment is dynamic, its memory handle is 
initially marked as purgeable but locked (temporarily unpurgeable 
and fixed; subject to change at the request of the application). If 
the dynamic segment is position-independent, its memory handle 
is marked as movable; otherwise, it is fixed. 

In summary, a typical load segment will be placed in a memory 
block that is 

□ locked 

□ fixed 

d purge level = (that is, unpurgeable) if the segment is static 
a purge level = 1 if die segmem is dynamic 

Depending on other requirements the segment may have, such as 
alignment in memory, the load segment- memory block 
relationship may be more complex. Consult the Apple IIGS 
ProDOS 16 Reference for del ails. 



Loading programs and segments 

The System Loader loads all programs and segments of programs. 
It is called by ProDOS !<5 when an application starts or quits, it is 
called automatically to load dynamic segments during program 
execution, and it can be called by your application to load and 
unload other programs or program segments. This section 
describes both the automatic operation of the loader and the 
ways in which your program can call it directly. 

♦ Note: If you are writing a typical application, you don't have to 
call the System Loader at all. All its operations are automatic 
for most programs, even those with dynamic segments. If you 
are not interested in System Loader details, skip ahead to 
"Quitting and Launching Under ProDOS 16." 

♦ Hodgepodge.- Hodgepodge makes no loader calls. 



Loading programs and segments 195 



ThB System Loader, although o 
tool set, is documented in the 
Apple lies ProDOS 16 Reference 



The Jump Table, Pathname 
Table, and other System Loader 

tables are discussed In detail in 
the Apple ilGS ProDOS 16 
Referenea 



How the System Loader works 

The System Loader is the Apple IIGS tool set that manages the 
loading of program segments into the Apple IIGS. It works very 
closely with the Memory Manager and with the ProDOS lfi 
operating system. 

The System Loader is a program that processes load files — it is 
not concerned with source files or object files. Each load file 
consists of load segments that the loader treats differently, 
depending upon their attributes: 

■ Static segments are loaded into memory at application startup. 
They stay in memory until the program quits. 

■ Dynamic segments are placed in memory only as needed 
during program execution. They may be removed when no 
longer needed- 

■ Absolute segments are loaded at specified, fixed locations in 
memory, 

■ Relocatable segments are placed wherever the System Loader 
can find sufficient memory space. Once they are loaded, their 
memory blocks are locked so they can't move. 

■ Position-independent segments are placed wherever the System | 
Loader can find sufficient memory space. Their memory blocks 
are initially locked, but once unlocked they can be moved from 
one location to another between executions. 

Some load segments consist of typical program code or data; 
others are more specialized. The Jump Table segment, when 
loaded into memory, becomes the Jump Tablej it provides a 
mechanism by which segments in memory can trigger the loading 
of other needed segments. The Pathname segment becomes the 
Pathname Table, a cross-reference between pathnames on disk 
and load segments in memory. An Initialization segment 
contains any code that has to be executed first, before the rest of 
the segments are loaded. 

When the System Loader is called to load a program, it loads all 
static load segments and constructs the tables necessary to allow 
automatic loading of dynamic segments. 
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Controlling programs a ro 
discussed under "Loading 
Applications/ later in this section. 



To unload a segment, the System Loader calls the Memory 
Manager to make the corresponding memory block purgeable. If 
the segment is dynamic, the loader also alters the jump Tabic to 
reflect the fact that the segment may no longer be in memory. 

To unload all segments associated with a particular application 
(for example, at shutdown), a controlling program such as a shell 
calls the System Loader's User Shutdown function, which in turn 
calls the Memory Manager to make purgeable, purge, or 
dispose of the application's memory blocks (depending whether 
the application is rcstartable or not — see "Shutting Down and 
Restarting Programs in Memory,™ later in this section). 



Loading a relocatable segment 

When a relocatable segment is loaded into memory, its code is 
placed at the location assigned to it by the Memory Manager. The 
loader then performs relocation on the code — it patches address 
operands that refer to locations both within and external to the 
segment. 

1, Local references are coded in the load segment as offsets from 
the beginning of the segment. The loader adds the starling 
address of the segment to each offset, so that the correct 
memory address is referenced, 

2 External references may be to routines in static or dynamic 
segments- If the reference is to a static segment, the loader 
finds the memory location of the routine in that static segment 
and patches the reference with its address. If the reference is to 
a dynamic segment, the loader patches the reference to point 
to a Jump Table entry. The Jump Table entry contains the 
information necessary to transfer control to the external 
segment when it is loaded. 

You can see that most Apple IIGS code cannot be moved once it 
is in memory: relocation happens only when the segment is 
loaded, so if the segment is ever moved its address operands will 
no longer be correct. Only position-independent code, which 
needs no relocation, can be moved around in memory. And 
position -in dependent code is difficult to write — therefore, most 
Apple IIGS code is relocatable, but not position-independent. 



Loading programs and segments 
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Object modulo format Is the file 
format produced by Apple I is 5 
development systems such as 
the Apple itss Programmer's 

Workshop. See Chapter 7. 



Loading applications 

The functioning of the System Loader is completely transpar« 
10 most applications. Any program that is in proper object 
module format (with any combination of static and dynamic 
segments) will be automatically loaded, relocated, and executed 
whenever it is called, Unless you want your program to load 
dynamic segments manually, or load and execute other progams, 
you need not know how to use the System Loader. 

However, you can indirectly affect the functioning of the System 
Loader by the method in which you segment your programs, If 
your program is divided into static and dynamic segments, you 
may experiment with several configurations of a single program 
after it has been assembled to see how loading of dynamic 
segments affects performance. See Chapter 7 for further progrim 
design considerations involving static and dynamic segments. 



Application control ol segment loading 

Most applications do not need to make loader calls directly, 
for programs with specialized requirements the System Loader 
offers this capability. 

One advantage of manually loading a dynamic segment is that j 
segment can be referenced in a more direct manner than an 
automatically loaded dynamic segment. Automatically loaded n 
dynamic segments can be referenced only through a JSL to thej 
Jump Table; however, if the segment consists of data such as a 
table of values, you would want to simply access those values 
rather than passing execution to the segment. By manually 
loading the segment into a locked memory block, and 
dereferencing its memory handle (obtaining a pointer to the staK 
of the segmenL), you can then reference any location in the 
directly. Of course, because the loader does not resolve any 
symbolic references in the manually loaded segment, the 
application must know the segment's exact structure. 

Your program is responsible for managing the segments it loadt 
That is, it must unload them with System Loader calls when theyj 
are no longer needed. 



198 



Chapter 6: Memory, Segments, and Files 




ThaProDOS 1 6 QUrf califs 

explained under "Quitting and 

Launching Under Pro DOS 16," later 
nthls chapter, 



More detailed requirements for 
controlling programs and their 
subprograms (called shell 

applications) are listed in 
Chapter 8. 



Loading by controlling programs (shells) 

A program may cause the loading of another program in one of 
two ways: 

□ The program can make a ProDOS 16 QUIT call. ProDOS 16 
and the System Loader remove the quitting program from 
memory, then load and execute the specified new program. 

□ The program can call the System Loader directly. The loader 
loads the specified new program without unloading the original 
program, then hands control back to the original program. 

Most applications use the first method. Even if you want your 
application to launch another specific program, and even if you 
want control to return to your application after the succeeding 
program quits, the ProDOS 16 QUIT call is all that is needed. For 
example, a finder or program launcher, which always regains 
control between execution of applications, uses the QUIT call to 
launch the applications. 

Programs thai use the second method are called controlling 
programs. Certain types of finders, switchers, and shells may be 
controlling programs. ProDOS 16 is a controlling program; the 
Apple IIGS Programmer's Workshop Shell is a controlling 
program. An application needs to be a controlling program only 
if it must remain in memory after it calls another program, usually 
because it has functions or sets up an environment needed by the 
programs it executes. 

The controlling program is completely responsible for the 
subprogram's ultimate disposition. When the subprogram is 
finished, the controlling program must remove it from memory 
and release all resources associated with its User TD. The best way 
to do this is to call the System Loader's User Shutdown function. 



Shutting down and restarting programs in memory 

By using System Loader calls, a controlling program can rapidly 
switch execution among several applications. For switching to be 
efficient, the loader must be able to shut a program down without 
removing it from memory! and the program must be able to re- 
execute itself without having to be reloaded from disk. 
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Restarrqble software reinitializes 
its variables every time It gains 
control; It also makes no 
assumptions about the state of 
the machine it will find when it 
starts up. 



The User Shutdown function can put an application into such a I 
dormant state. It does this by purging an application's fiyrcsmfcj 
segments, and making all its static segments purgeable. This 
process frees space but keeps the dormant application's essential 
segments in memory, As long as all the static segments are still i 
memory, the Restart function brings the application back rapid 
because disk access is not necessary. However, iF for any reason] 
the Memory Manager purges one of those static segments, the 
application can no longer be restarted — the next time it is 
needed, it must be loaded from its disk file. 

Only software that is restartable can be executed in this way. In 
general, if your program has a code routine that defines and 
initializes all variables, and if that routine is called every time th 
program runs, and if the code in that routine is not modified 
during execution, the program is probably restartable. 

When an application quits with a ProDOS 16 QUIT call (descri 
next), it tells its controlling program whether it (the application! 
is restartable or not, (The controlling program simply takes the 
application's word for this, by the way.) If the application says il 
wants to be restarted and claims to be restartable, the control 
program makes it dormant. If the application says it is not 
restartable, the controlling program removes all of its segments 
from memory. 

•fr Note: It is difficult to make some programs in some languag 
restartable; they require initialization information to be load 
Tram disk every time they execute. To help in such cases, the 
System Loader supports RELOAD segments. If all mitializaiia 
information is put into a RELOAD segment, a program that 
could not otherwise be restarted can make itself restanable 
When a program is restarted from a dormant state, only its 
RELOAD segments (plus any initialization segments) are reac 
from disk. 



Quitting and launching under ProDOS 16 

ProDOS 16 and the System Loader provide a sophisticated 
method for passing control among different applications. 
Through the ProDOS l6 QUIT call, an application can do one i 
three tilings: 

a Quit permanently. 
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The system fie level is described 
later In this chapter, under "the 

ProDOS File System, ' 



D Quit permanently, but tell ProDOS 16 to launch another 
specified application, 

a Quit to a specified application temporarily, telling ProDOS 16 
it wants to be re-executed after the specified application quits. 

When it launches another application or quits temporarily 
through the QUIT call, an application is not functioning as a 
controlling program. It is not maintained in memory (except, 
possibly, in a dormant state) while the other program executes. A 
finder or program launcher, for example, is an application that 
quits temporarily each time an application is launched, returning 
after the application quits, It is not a shell. 

♦ Nate: If you are writing a typical application in a high-level lan- 
guage, you may not need any of the information here — your 
compiler determines the manner in which your program quits. 
If you are writing a typical application in assscmbly language, be 
sure to read the "Hodge Podge" note at the end of this section. 



Quitting, launching, and returning 

Calling QUIT terminates the present application. It also closes all 
open files, sets Lhe current system file level to zero, and 
deallocates any installed interrupt handlers. ProDOS l6 can then 

□ launch a file specified by the quitting program 

□ automatically launch a program specified in the quit return 
stack 

The quit return stack is a table of User ID'S maintained in memory 
by ProDOS 16. It provides a convenient means for a program to 
function like a shell — the program can pass execution to 
subsidiary programs (even other shell-like applications), while 
ensuring that control eventually returns to it. 

For example, a program selector may push its User ID onto the 
quit return sLack whenever it launches an application (by making a 
QUIT call). That program may or may not specify yet another 
program when it quits, and it may or may not push its own User 
ID onto the quit return stack. Eventually, however, when no more 
programs have been specified and no others are waiting for 
control to return to them, the program selector's User ID will be 
pulled from the slack and it will be executed once again. 

When your application makes a QUIT call, it specifies these two 
parameters: 
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The exact format of the flag word, 
and the rest of the RroDOS 16 QUO* 
call, is given in the Appte Hs$ 
RoDOS 16 Reference. 



Using the PtoOOS 8 QUIT call on the 
Apple IIGS is discussed In the 
Apple IIGS ProDOS }6 Reference. 



1. Pathname pointer — if .specified, it indicates the program to be 
loaded and executed. If no pathname is specified, ProDOS 16 
pulls a User ID from the quit return stack and executes the 
program with that User ID. 

2 Flag word — it contains two boolean values.- a return flag and a 
restart -from-memory flag. The return flag tells ProDOS l6 j 
whether the program making the QUIT call wants to return; if 
so, its User ID is pushed onto the quit return stack. The restart- 
From-memory flag tells ProDOS 16 whether the quitting 
program is restartable. If it is not, the program must be 
reloaded from disk the next lime it is run The information 
from this flag is saved on the quit return stack along with the 
User ID. 

■fr ProDOS & This automatic return mechanism is specific to the 
ProDOS 16 QUIT call, and therefore is not available to ProDQ 
8 programs on the Apple IIGS. When a ProDOS 8 application 
quits, it can pass control to another program but it cannot put 
its own ID on the quit return stack. 

How a particular application quits is language-specific. For 
example, C programs terminate with a left -facing bracket, and 
Pascal programs end with an END , statement. In cither case there 
is no way to make an explicit QUIT statement. The actual quit 
statement is inserted when the program is compiled. Assembly- 
language programs, however, make explicit QUIT calls. 

<• UodgePodge: The assembly-language version of HodgePc 
has the followingProDOS 16 (macro) QUIT statement: 

Quit QuitParams 

where the _Quit macro translates directly into a ProDOS 
QUIT call, and the QuitParsms parameter list consists off 
null bytes (corresponding to a null pathname pointer), 
followed by a word- length flag value of $4000 (meaning that 
HodgePodgc is restartable from memory). 



Setting up direct-page/stack space 

For assembly-language programmers, the 65C816 processor 
provides the convenience of a direct page. Accessing and 
indexing from direct-page addresses are efficient because adi 
operands are a single byte, rather than the three bytes rec 
for a full address on the 65C816. 



202 



Chapter 6: Memory, Segments, and Files 



Stondord-Appla II stock and zeio 

nog© aie discussed In the Apple 
lie Technical Reference Manual 
did the Apple tie Technical 
Reference Manual 



For all programmers, direct page is of interest because several 
Apple 1IGS tool sets require that the application provide direct- 
page space for them. 

The size and location of the stack may also be of particular 
interest to you if you are writing heavily recursive routines that 
require large stack space. 



How direct page and stack are organized 

In the Apple IIGS. the 65C816 microprocessor's stack pointer 
register is 16 bits wide; that means that the hardware stack may be 
located anywhere in bank $00 of memory. Also, the stack may be 
as much as 64K deep. In theory, then, the stack may occupy any 
unused space of any size in bank $00. 

The direct page is the Apple IIGS equivalent to the zero page on 
a standard Apple II computer. The difference is that it need not 
be page zero in memory. Like the stack, the direct page may be 
placed in any unused area of bank $00. The microprocessor's 
direct register (D register) is 16 bits wide, and all zero-page 
(direct-page) addresses are added as offsets to the contents of 
that register. Because the direct page can be located anywhere in 
bank S00, you can allocate more than 256 bytes (that is, more 
than one page) as direct-page space for your program. Then, by 
changing die value of the D register while the program is running, 
you can use direct addressing to access any portion of the direct 
page space. 

In principle, the endre 64K of bank $00 could be used for the 
combined direcl-page/stack space. In practice, however, less space 
is available. First, only the lower 48K of bank $00 can be allocated, 
the rest is reserved for I/O and system software. Also, because 
more than one program can be in memory at a time, there may 
be more than one stack and more than one direct page in bank 
500. Furthermore, many applications may have parts of their code 
as well as their stacks and direct pages in bank $00. 
Your program should therefore be as efficient as possible in its 
use of direcl-page/stack space. The total size of both should 
probably not exceed about 4K in most cases. Still, with a space 
that size you can write programs that require stacks and direct- 
page space much larger than the 5 12 bytes available on standard 
Apple II computers. 
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♦ Note: By convention, ihe direct page and stack occupy a sitS 
memory block in bank $00, Direct-page addresses are possH 
offsets from the base of the allocated space, and the stack growj 
downward from the top of the space. 



Creating a direct-page/stack segment 

Only you can determine how much stack and direct-page spaci 
your program will need when ii is running. The beat lime lo aam 
that determination is during program development, when you 
create your source files. There are three ways to allocate the 
direct-page/stack space you need: 

□ Define it as a program segment, 

□ Use the ProDOS 16 default. 

□ Create it at run time. 



Define it as a program segment 

You can specify the size and contents of your program's ; 
direct-page space by creating a direct-page/stack segment ■ 
you assemble Cor compile) and link your program. The size ■ 
segment is the loial amount of stack and direct-page space 
allocated to your program, and the contents of the segment ; 
whatever initial contents you want the direcl-page/stack space 
to have. 

Each time a program is started, the System Loader looks for i 
dircct-page/stack segment. If it finds one, it loads the segments 
passes its base address and size to ProDOS 16, along with the 
program's User ID and starting address. ProDOS 16 sets the A 
(accumulator), D (direct), and S (stack) registers as shown belo 
then passes control to the program. 



Register Contents 

A User ID assigned to the program 

D address of the first (lowest) byte in the dircct- 

page/siack space 

S address of the last (highest) byte in the direct- 

pagc/stack space 
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UritEd Is described in the Apple 

ISS Programmer's Workshop 
ffaferenca An example of a 
UnkEd f t9 Is shown In "Creating 
Segmented Cods: Three 
Dimples' in Chapter 7. 



KIND Is a segment-description 
ffta. See "Object Module 
format" In the Apple ties 
Programmer's Workshop 
Inference or "System Loader 
Technical Data' in the Apple ISGS 
ProOOS 16 Reference, 

1 

Create an 

object segment 

of proper size. 

Object file: 



To specify ihe direct- page/stack space for your program use Ote 
following procedure (in APW assembly language, using LinkEd). 
See also Figure 6-5. 

1 Create a dau segment in your source file with the size and 
contents you want for your Initial direct page and stack. 

2 Assemble the program. 

3. Use a LinkEd file to link the program. Make the direa- 

page/stack segment a load segment by itself, with KIND=S0812 
(meaning it is a static, absolute-bank, direct-p age/stack 
segment). 



Place it In a single 

direct-page/stack 

load segment. 

Load lile: 



1 



Segment 1 



Segment 2 



Segment l 



The System 
Loader 

loads it 
Into 
Bank 
S00. 



ProDOS 16 sets the 
stack register to 

the highest address 
In the segment. 



Segment m 



i 



Linker 



Segment n 



Loader 



Direct page 
and stack 



ProDOS 16 sets the 
direct register 
to the lowest 

address In 
the segment 



Figure 6*5 

Loading a direct- page/stack segment 
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See theAppte Mgs Toolbox 
Refemncetor a general 
description of memory biock 
attributes assigned by ths 
Memory Manager 



Hodgepodge's direct-page 
allocation lor too! sets Is 
demons! rated under "Start the 
Program* in Chapter 2. 



Use the ProDOS 16 default 






If the loader finds no direct-page/stack segment in a file at load 
time, ProDOS 16 itself calls the Memory Manager to allocate a 
default direct-page/stack segment, in a memory block with these 
attributes: 



Size 
Owner 

Fixed/movable 

Lock ed/u nl ocked 

Purge level 

May cross bank boundary? 

May use special memory? 

Alignment 

Absolute starting address? 

Fixed bank? 



1,024 bytes 

program with the User ID 

returned by the loader 

fixed 

locked 

1 

no 

yes 

page-aligned 

no 

yes — bank $00 



Once allocated, the default direct-page/slack space is treated just 
as it would be if it had been specified by the program: ProDOS lfi 
sets the A, D, and S registers before handing control to the 
program, and at shutdown the System Loader makes die segment 
purgeable. 

For many assembly- language applications, the IK default stack 
and direct page space allocated by ProDOS 1.6 are sufficient. 
Individual high-level language systems may have the same or 
different default sis-es; check your language reference manual. 

♦ HodgePodge: Hodgepodge accepts the default direct- 
page/stack space set up for it by ProDOS 16. In addition, it 
manually creates a direct-page space for tool sets, by a method 
similar to that described next, under "Create It at Run Time. 



Create it at run time 






If the ProDOS 16 default space is the wrong size for your applica- 
tion, and if for some reason you do not want to specify the size of 
your direct-page/stack space at link time, you can include ProDOS 
16 and Memory Manager calls in your program that allocate a 
direct-page/stack space during program execution. In that case, 
when ProDOS 16 transfers control to your program, save the User 
ID value left in the accumulator (or use the User ID returned by 
the Memory Manager startup call) before doing the following 
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1. Using the starting or ending address left in the DorS register 
by ProDOS 16, make a FindHandle call to the Memory 
Manager to get the memory handle of lhe automatically 
provided direct- page/stack space. Then, using that handle, get 
rid of the space with a Disposer Iandle call. 

2. You can now allocate your own direct- page/stack space through 
the Memory Manager NewHandle call. Make sure that the 
allocated block is purgeable, immovable, and locked. 

3. Place the appropriate values (beginning and ending addresses 
of the segment) in lhe D and S registers. 



Cautions 

When your program terminates with a QUIT call, the System 
Loader makes the direct-page/stack segment purgeable, along with 
the program's other static segments. Bank $QQ is heavily used, and 
if the direct-pagc/stack segment is purged, your entire program 
will have to be reloaded from disk when it reexecutes. 

If your direct-page/stack load segment contains initialization data, 
you need to make it a RELOAD segment if you want your program 
to be restartable. 

There is no provision for extending or moving the direct- 
page/stack space after its initial allocation. Because bank $00 is so 
heavily used, the space you request may be unavailable— the 
memory adjoining your stack is likely to be occupied by a locked 
memory block. Make sure that the amount of space you specify at 
link time fills all your program's needs. 



Important The Apple IIgs provides no mechanism for detecting stack 

underflow or overflow (collision of the stack with the direct page). 
Vour program must be carefully designed and tested to make sure 
this cannot occur. 



The tefm ProDOS Cos in ProDOS file 
system) refers to features 
common to both ProDOS 8 and 
ProDOS 16. The term ProDOS 16 {as 
In ProDOS 16 prefixes ) Is used to 
describe features that PioDOS 6 
does not have. 






The ProDOS file system 

You use the Apple IIGS disk operating system, ProDOS 16, to 
open, close, create, delete, and otherwise manipulate files on disk. 
This section describes the filename and prefix conventions used 
by ProDOS 1 6 and introduces some of the ProDOS 16 functions 
that your program may call. 



The ProDOS file system 



20? 



Filenames and pathnames 



A ProDOS filename or volume name iumtmc u 
It may contain uppercase letter'™) 71 (0 « tlT"* 5 
^d it must begin with a leuer, I^^?' , i penQd 
converted to uppercase A HT«J "^^^e letters are automate 
directory. PP& ^ Se A niename ™st be unique within to 



S«^^^!i a ^ ° f ^names, each preceded!, 



Pathname prefixes 

volume name The m „ imilr !, ^ * Slash and doesn l delude 
characters, mclu^ ST ^ f ° r * pa ' lial P ath — « - « 

f <»e irom ine partial pathname. When Pmnn<: K 
prefixes are as follows: ™ C P redefi ^d 
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See the ProDOS 3 Technical 
Reference Manual fat more 
Informotion on ProDOS 8 prefix 
cawAntlons. 



Table 6-2 

Examples of prefix use 

Case Illustrated 



* / Boot prefix: the name of the volume from which the 

presently running ProDOS 16 was booted. 

0/ Default preflxj (automatically attached to any partial 

pathname that has no prefix number)— it has a value 
dependent on how the current program was launched In 
most cases the default prefix is equal to the boot prefix. 

1/ Application prefix; the pathname of the subdirectory 

that contains the currently running application, 

2/ System library prefix: the pathname of the subdirectory 

(on the boot volume) that contains the library files used 
by applications. 
3/_7/ Null strings; (unless previously defined by an application). 
Your application may change the values of all prefixes except 
prefix */. 

Prefix 0/, the default prefix, is similar to the ProDOS 8 system 
prefix in 'that ProDOS l6 automatically attaches prefix 0/ to any 
partial pathname for which you specify no prefix. However, us 
initial value is not always equivalent to the ProDOS 8 system 
prefix's initial value. 

The maximum length for a prefix is 64 characters. The minimum 
length for a prefix is zero characters; a prefix of zero length IS 
known as a mill prefix. You set and read prefixes using the calls 
SET.PREFIX and GET_PREFIX. The 64-character limits for the 
prefix and partial pathname combine to create a maximum 
effective pathname length of 128 characters. 

Table 6-2 shows same examples of prefi* ^.- ' 11 ' 1C P aLhn;ltnc 
provided by the caller is compared with the full pathname 
constructed by ProDOS l6. The examples assume that prefix 0/ is 
/VOLUMEl/ and prefix 5/ JS / VOLUME 1/ TEXT. FILES/ 



path na me provided 



Pathname as expanded 



Full pathname / VOLUME 1/ TEXT, files /CHAP. 3 /VOLUMEl /text, files /chap. 3 

implicit use Of prefix 0/ TEXT .FILES/ CHAP .3 / VOLUME 1 /TEXT. FILES/ CHAP . 3 

Explidtuse Of prefix 0/ /TEXT. FILES /CHAP .3 /VOLUMEI/TEXT. FILES/CHAP. 3 

Use of prefix 5/ 5/CHAP.3 /VOLUMEl /TEXT .FILES /CHAP . 3 

MM: These examples assume that prefix 0/ is set to /volume 1/ and that prefix 5/ is set to 

/VOLUMEl /TEXT. FILES/. 
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Important When your application is launched, ail nine prefix numbers are 

assigned to specific pathnames (some are meaningful pafhr>ar..„ 
and others may be null strings). However, prefixes □ / and 2/ may 
not have the expected ProDOS 16 default values -they may 
reflect changes made by the previous application. Beware of 
assuming any particular initial value for an 1 / particular prefix, 



AN of these file attributes or© fully 
explained In Appendix A of the 
Apple lies ProDOS 16 Reference. 



Creating and destroying files 

A file is placed on a disk by the ProDOS 16 CREATE call. When 
you create a file, you assign it several properties, including 

□ pathname 

P access attributes (deletable, renamabie. writeable, readable, 
backup-required) 

□ file type 

D auxiliary type 

□ creation date and creation time 

Once a file has been created, it remains on the disk until it is 
deleted (by using the DESTROY call). 



Opening, closing, and flushing fifes 

Before you can read information from or write information to a 
file, you must use the ProDOS 1 6 OPEN call io open the file for 
access. The OPEN call returns a reference number for the file. All 
subsequent references to the open file must use its reference 
number. The file remains open until you use the CLOSE call on it. 

When you finish reading from or writing to a file, you must use „ 
CLOSE call to close the file. CLOSE writes any unwritten data fron 
the file's I/O buffer to the file, and it updates the file's size in the 
directory if necessary, To access the file again, you have to 
reopen it. 

FLUSH, like CLOSE, writes any unwritten data from the file's I/O 
buffer to the file, and updates the file's size in the directory. 
However, FLUSH keeps the file open. 
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File levels 

When a Hie is opened, it is assigned a file level according to the 
system file level You can determine the current system file level 
with a GET_LEVEL call, and can change the level with a 
SETJLEVEL call- When you specify as Lhe reference number in 
the CLOSE and FLUSH calls, all files having a File level greater 
than or equal to the current system Tile level are closed or flushed. 

This feature allows controlling programs to quickly close all files 
associated with their subprograms. For example, when a shell 
program takes control of the Apple lies, it can execute a 
GET_LEVEL call to determine the current system file level, then 
execute a SETJ.EVEL call to set the system file level to a higher 
level. Each file opened by the shell and by the programs that run 
under the shell is then assigned the new file level by ProDOS 16. 

When the shell is ready to quit, it can execute a CLOSE call with a 
reference number of 0, and all files opened under the shell (that 
is, those with a file level equal to or greater than the current 
system file level) are closed. The shell can then execute a 
SET_LEVEL call to return the system file level to its previous value, 
and finally execute a QUIT call. 



Reading and writing files 

READ and WRITE calls to ProDOS 16 transfer data between 
memory and a file. For both calls, the application must specify 
the location in memory of a buffer that contains, or is to contain, 
lhe transferred data. When the request has been carried out, 
ProDOS 16 passes back to the application the number of bytes 
that it actually transferred. 

A read or write request starts at a specific position in the file, and 
continues until the requested number of bytes has been 
transferred (or, on a read, until the end-of-file has been reached). 
Read requests can also terminate when a specified character (the 
newline character set by the NEWLINE call) is read. 
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LoadOne is in the source file 
PAINT.PAS. 



The HodgePodge routine that reads files is LoadOne, called froa 
the routine AskUser, which itself is called from DoTheOpen 1 
the user wants to open a picture window. LoadOne makes the 
ProDOS 16 calls OPEN, READ, and CLOSE; 



function LoadOne: Boolean; 
var 



openBlk 

readBlk 



OpenRec; 

FilelORee; 



begin 

LoadOne :- FALSE 

WaitCuraor; 

pictHndl := Hav#Handle($6000 r 

rayMemorylD, 
0, 

Ptr(O)); 
if isToolError then 
Exit/ 

HLock(pictHndl) ; 

openBlk . openPathname s- 

@myReply . f ullPathname; 
openBlk.ioBuffer s- NIL; 

OPEN (openBlk) ; 
if CheckDiakError (27) then 
Exit; 



readBlk . databuf f er 
readBlk . requestCount 
readBlk . f HeRefNum 



pictHndl*; 

S6000; 

openBlk .open RefNum; 



READ (readBlk) • 

i f CheckD i skErro r ( 2 8 ) then 

Ex IN- 
CLOSE (readBlk) ; 
HOnLock (pietHndl) ; 

LoadOne :- TP.UE; 
end; 



(begin LoadOne..,} 

(ProDOS 16 parameter blacks,.,) 
(...defined in ProDOS 16 interface! 



{Initialize value of function} 

{put up watch cursor} 

{request memory to hold the picture,.] 

{Hodgepodge's User ID} 

{not purgeable, no restrictions} 

{anywhere) 

(If the memory is unavailable...} 

(...leave this subroutine} 

(Lock handle so picture won't move) 
(Now fill in parameter block:...} 

(pathname from Std. File results..} 
{zero this parameter} 

{make a ProDOS 16 OPEN call} 

(If it fails for some reason...} 

(...display error and exit) 

(Fill in parameter block for READ:. 

(pointer to where to put data) 

(requested no. of bytes to read) 

(file* 3 reference number} 

(make a ProDOS 16 READ call} 
[If it fails for some reason,.,} 
{,., display error and exit) 
{Open file no longer necessary:..} 
{Make a ProDOS 16 CLOSE call) 
(Unlock the handle until we.,.) 
{...need the picture again} 
(function successfully completed) 

(end of LoadOne) 
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eOne Is in the source file 

UNT.PAS. 



The HodgePodge routine that creates files and saves Lhem to disk 
is SaveOne. It is called from the routine DoSaveltem (which. 
saves the contents of a picture file to disk), described under 
"Communicating With Files and Devices" in Chapter 5. SaveOne 
makes the ProDOS \6 calls CREATE. DESTBOY, OPEN, WRITE, 
and CLOSE: 



Ocedure SaveOne (pict: Handle); 



destroyBlk 

crca: eBl !■: 

openBlk 

uriteBlk 



PathnameRec; 
FileRec; 
QpsnRec ; 
FilelORec; 



(begn SaveOne-.} 

{a ProDOS 16 parameter block} 
{a ProDOS 16 parameter block} 
{a ProDOS 16 parameter block} 
{a ProDOS 16 parameter block} 



destroyBlk . pathname :- 

G my Reply . fullPathname; 

DESTROY (destroyBlk) ; 

createBlk, pathname :— 

G myReply . f ul IPathn ame ; 
creat eB Ik . f Ac ce 3 s : ■ $ C 3 ; 

cieateBlk.fileType := SCI; 
cieateBlk.auxType :■ 0; 

createBlk.storageType:- 1; 
create Ik. createDate :- 0; 
ereateBlk . createTime :- 0; 



(Put pathname from DoSaveltem..} 
(...reply record into param. block} 

(Delete any existing file with 
that pathname} 

(But the pathname in the block...,} 
(...give it this access value-.) 
(...assign a file type (unpacked).,,) 
(...aux. type - 0...} 
(...make it a seedling file...) 
(...let ProDOS 16 assign...} 
(...creation date and time.} 






CflEATE (createBlk) ; 

if CheckDi skEr ror (25) then 

Exit,- 

aper31k.openPathname :- 

GmyReply . £ullPatllname; 
apenSlk.ioBuffe^ :- NIL; 

OPEH (openBlk) ; 

writeBlk. dataBuffer :- pict*; 
writeBlk. request Count ;- $8000; 
WciteBlk.lileRefNum :- openBlk . fileRefNum; 
WRITE (writeBlk) ; 
i f Check DiskEr ror (26) then 
Exit; 

ClflSE (writeBlk) ; 



6ad; 






(Create the new file} 

(If the file can't be created..} 

(„,di splay error and exit} 



(Put the pathname into the block} 
( (this field must be zero] } 

(Open the file we've juat created} 
(Make a pointer to the buffer—) 
(...from the handle to the picture} 
(Transfer the entire 32K-byte file) 
(supply file* a ref__num) 
(Write the data to the file} 
(If the file can't be written to,..) 
(-.display error and exit} 

(Close the file) 

(End of SaveOne) 
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Brief explanations of certain 
ProDOS 16 parameters, such as 
access and fife type, are found 
elsewhere In this section, 



For more Information on all file 
attributes, see Appendix A of the 
Apple iigs ProDOS 16 Reference 



The parameter lists for the ProDOS 16 calls used in LoadOne and 
Save One are all combined into the single record Pl6Blk, 
defined in the Pascal interface library to ProDOS 16. Complete 
documentation of required parameters for all PraDOS 1 6 calls is 
in the Apple HGS ProDOS 16 Reference. 

The EOF and Mark 

To aid reading from and writing to files, each open file has one 
number indicating the end of the file (the EOF), and another 
defining the current position in the file (the Mark), ProDOS IS 
moves (increments or decrements) both the EOF and the Mark 
automatically when necessary, but an application program cm 
also manipulate them independently of PraDOS 16. 

The EOF is the number of readable bytes in the file. The Mark 
cannot exceed the EOF. If during a write operation the Mark meets 
the EOF, both the Mark and the EOF are moved forward one 
position for every additional byte written to the file. 

To move the EOF and Mark, use the SE'r_EOF and SET_MAKK 
calls. To determine the current values of the EOF and the Mark, 
use the GET_EOF and GET_MARK calls. 

♦ Hodgepodge. HodgePodge doesn't pay much attention to EOF 
and Mark in its file access, because it reads and writes only 
entire files at a time. 



File attributes 

The directory entry for each file contains information that 
be useful to your program. This section describes the folio? 
fields in directory entries and headers: 

□ creation and last-modification dates 
M access attributes 
P file type 

□ auxiliary type 

If you want to know the properties of a given file, use the 
GET_FILE_INFO call. If you want to change the file's name, usei 
CHANGE_PATH call. To alter the other properties use the 
SET_FILE_lNFO call. 
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Creation and last -modification date and lime 

The date and time of creation of a file are stored in the file's 
directory entry. When your program creates a new file, ProDOS 16 
automatically gives the (lie the current system date and lime. 
When your program modifies a preexisting file, ProDOS 16 
automatically sets the last-modification date and lime to the 
current date and time. In general, your program should not have 
to change these attributes. 

Access 

The access attribute field, or access byte, determines whether the 
file can be read from, written to, deleted, or renamed. It also 
contains a bit that can be used to indicate whether a backup copy 
of the file has been made since the file's last modification. 

ProDOS 16 sets the backup bit whenever the file is changed (that 
is, after a CREATE, RENAME, CLOSE after WRITE, or 
SET_FILE_INFO operation). This bit should be reset by a backup 
utility (using CLEAR_BACKUP_BIT) whenever it makes a backup 
copy of the file. No other program should ever reset the backup 
bit. 

<• HodgePodge: When HodgePodge creates its picture files, it 
assigns them the access value of SC3, meaning that they may 
be destroyed, renamed, read from, and written to. 

File type 

The f ile_type field in a directory entry identifies the type of 
file described by that entry. This field should be used by 
applications to guarantee file compatibility from one application 
to the next. The currently defined hexadecimal values of this byte 
are listed in Table 6-3 

Table 6-3 also lists the 3-character mnemonic file-type codes that 
might appear in catalog listings. For any file type without a 
specified mnemonic code, most catalog programs substitute the 
hexadecimal file type number. 

5 is the operating system for ♦ SOS: SOS file types are included in Table 6-3 because SOS and 

3 Apple III computer. ProDOS have identical file structures. Each may read the 

other's files, 

♦ HodgePodge: When HodgePodge creates its picture files, it 
assigns them the file type $C1 (picture file, unpacked format). 
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Table 6-2 






ProDOS f 


lie types 
Coda 




File type 


Description 


$00 




Uncaiegorized file (SOS and ProDOS) 


SOI 


BAD 


Bad block file 


$02 * 


PCD 


Pascal code file 


$03 ♦ 


PTX 


Pascal text file 


$04 


TXT 


ASCII text file (SOS and ProDOS) 


$05 • 


PDA 


Pascal data file 


$06 


BIN 


General binary file (SOS and ProDOS 8) 


$07 * 


FNT 


Font file 




$08 


FOT 


Graphics screen file 




$09 * 


BA3 


Business BASIC program file 




$0A * 


DA3 


Business BASIC data file 


$0B ' 


WPF 


Word processor file 




$0C ♦ 


SOS 


SOS system file 




$QD-S0E 


• 


SOS reserved 




$0F 


DIR 


Directory file (SOS and ProDOS) 


S10 • 


RPD 


RPS data file 




$11 * 


RPI 


RPS index file 




$12 ' 




AppleFile discard file 




$13 * 




AppIeFile model file 




$14 * 




AppleFile report format file 




$15 ' 




Screen library file 




$16-$18 • 




SOS reserved 




$19 


ADB 


AppleWorks® Data Base file 




$1A 


AWP 


AppleWorks Word Proc. file 




SIB 


ASP 


AppleWorks Spreadsheet file 


$1C-$AF 




Reserved 


SBO 


SRC 


APW source file 


$B] 


OBJ 


APW object file 


$D2 


LIB 


APW library file 




SB3 


S16 


ProDOS 16 application program file 




$B4 


RTL 


APW mn-u'me library file 




SB5 


EXE 


ProDOS 16 shell application file 




$B6 


PIF 


ProDOS 1 6 permanent initialization file 




$B7 


TIF 


ProDOS 16 temporary initialization file 




$B8 


NDA 


New desk accessory 




$B9 


CDA 


Classic desk accessory 




$BA 


TOL 


Tool set file 
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Table 6-3 (continued) 
ProDOS file types 



File type 



Code 



Description 



SBB 

SBC 

$BD-$BF 

$C0 

SCI 

SC2-SEE 

SKF 

SFO 

$F1-$F8 

$F9 

$FA 

$FB 

5FC 

SFD 

SFE 

SFF 



FAS 

CMD 



INT 

IVR 

BAS 

VAR 

REL 

SYS 



Driver file 

General ProDOS 36 load file 

Reserved for ProDOS 16 

Apple IIGS picture file (packed formats) 

Apple IIGS picture file (unpacked format) 

Reserved 

Pascal area on a partitioned disk 

ProDOS 8 CI added command file 

ProDOS 8 user-defined files 1-8 

ProDOS 8 reserved 

Integer BASIC program file 

Integer BASIC variable file 

Applesoft program file 

Applesoft variables file 

Relocatable code file (EDASM) 

ProDOS 8 system program file 



'apply to Apple 111 (SOS) only 



Auxiliary type 

Some applications use another field in a file's directory entry, the 
auxiliary type field (auxtype), to store additional information 
not specified by the file type. Some catalog listings may display 
the contents of this field under the heading "Subtype." 

For example, APW source files (file type $B0) include a languagc- 
type designation in the aux_type field. The starting address for 
ProDOS 8 executable binary files (file type 506) may be in the 
aux_type field. The record size for random-access text files (file 
type $04) may be specified in the auxiliary type field. 
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For most file types, ProDOS 16 and ProDOS 8 impose no 
restrictions (other than size) on the content, or format of the 
auxiliary lype field. Individual applications may use those iwo 
bytes to store any useful information. 

* Hodgepodge: When HodgeFodge creates its picture files ft 
assigns them an auxiliary- type value of 0. It stores no 
iniormation in the auxiliary type field. 



SFGetFlle sends to OpenFilter only 
the file types specified In Its 

type List para met erases 

" Communicating With Files and 

Devices" in Chapter S. 



OpenFilter Is j n the source fife 
PA f. NT. PAS. 



Controlling user access to files 

type SCI. Because HodgePodge cannot handle other file types, 
me user should not be permitted 10 select anything but $C1 fil 

Zl^l n'^ U 7 ght be useful to let the U ™ «* ' f ** 
select, other files in a directory. 

The HodgePodge routine OpenFilter is called by the Stand 
Rle Operations Tool Set to find out how to display files of va 
2K*,;?, thC °Pf n diaI °S b«- For each file entry it encounter 
SFGetF.Ie caUs this routine. If the routine returns 0, the filem 
not d.splayed if the routine returns 1, the filename appears 
Cammed) but the file is not selectable; if the routine returns 2, 1 
filename 1S not dimmed and the file is selectable. OpenFilter 
dims all file types but SCI. 

The variable FileTypePtr below is a pointer to the file-type 
■eld ,n the directory entry for the file under consideration^ 
Ue-type field ,s at an offset of 10 bytes into ihe file entry 



Nation C^nFiltarfdi^tryaangint,: integer; 
type BytePtr = "byte; 

war fileTypePtr i BytePtr; 

begin 

fUeTVpePtr := Pointer (dirEntry + $10) . 
J B . 1 ! A f D(f±leT ^ ePt ^^00FF) - S clj then 



OpenFilter 
else 

OpenFilter 
end/ 



1; 



{begin OpenFilter..,} 



(Fir at, get a pointer to the file'.,} 
file type from its directory entry.} 
J If It's unpacked Picture File type } 
(...make it black and selectable) 
(If it's any other file type...) 
{...it's dimmed and nonaelectable) 
(End of OpenFilter} 
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program design a „ rf ,i" Li ° '" ,d sc "" ral hi "« °« 

life, ana 4 i™X ,5 ■ „"!; ir M "* " t - Em '» MI "'" "f o*| 
your program .„d IS , 7 ''>' >'"" ""* ta ™* "' •*»« 

<■* -II Wp you . te &™ 8 'ZX^f ° !0 "" ! "'"» 



Apple jigs Programmer's wSfcsh^T^ 

□ shell 

B linker 

3 utility fSfqg^tja 

comj'oiwnte of r|- e dcrel.Cn rUrfe " f ajld ^ 

^^^Sr«S£^ m em ^^<. **rtbed in 
a 6M3 assembler 

P tJtJJer compilers 
E debuggers 
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Program descriptions 

The programs included in the Apple IIC5 Programmer's 
Workshop relate to each other as illustrated in Figure 7-1. The 
APW Shell's command interpreter serves as the interface between 
you and Lhe rest of ihe Apple IIGS system. The shell allows you to 
call the other programs that constitute the Apple 1IG5 
Programmer's Workshop, and serves as the link between APW and 
the Apple IIGS Toolbox and operating system. The toolbox and 
operating system (including ProDOS 16, the System Loader, and 
the Memory Manager) are the interface between APW and Apple 
IIGS hardware and firmware- 




Apple IIGS hardware & firmwaie NN, 



ProDOS 16 



APW Shell 



Editor 



Linker 



_L 



Command Interpreter 



Debugger 



Compilers 



t 



L 




j ^ j . ' i j - 



j j j j j j. 






User 



Figure 7-1 

APW programs in the Apple Bgs system 



Shell 

The shell program is the interface that allows you to execute APW 
commands and programs. With it you can perform a variety of 
housekeeping functions, such as copying and deleting files or 
listing a directory. The shell supports input and output redirection 
and pipelining of APW programs. 
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ProDOS 16 calls are described in 
the Apple 115$ ProDOs Id 
Reference: 



Macros aie commands, each 
one of which replaces several 
assembly-language Instructions 
or assembler directives. When a 
program. Is assembled, the 
assembler replaces macros with 
their equivalent Instructions and 
directives. 



The shell also acts as an interface and extension to ProDOS 16 I 
providing several functions, called shell calls, [hat can be ailed 
by programs running under the shell. Shell calls can be used by 
utility programs, compilers, linkers, or assemblers to perform such I 
functions as passing parameters and operations flags between the 
shell and APW programs. The formal for making these calls Is 1 
exactly like that used for making a ProDOS 16 call. 

Editor 

This fullscreen text editor is designed for use with APW 
assemblers and compilers. It allows you to enter, copy, delete, and 
move text, and provides automatic search and search-and-replace 
functions. 



Assembler 

This full-featured assembler allows users to write 65816 assembly- 
Ianguage programs for the Apple IIGS computer, with complete 
support for the standard Apple lies file format and library files 
The Apple IIGS Programmer'sWorkshop Assembler includes 
macros to facilitate assembly-language programming, and allows 
users to wnte their own macros and library files. 

The APW Assembler is specifically designed for writing relocate 
code, because the APW Linker, System Loader, and Memory Man* 
are all designed to work most efficiently with relocatable code ( 



C Compiler 

The Apple IIGS Programmer's Workshop C Compiler is a 
complete implementation of the C programming language It 
consists of a C compiler, the Standard C Library, the Apple UGS 
Interface Libraries, and the C SANE Library. The object files 
output by the C compiler are fully compatible with those output 
by Lhe APW Assembler and consist of relocatable code. 

Linker 

The APW Linker takes the files (called object Jl(es) created by the 
APW Assembler or any of the APW compilers, and generates files 
that the System Loader can load into memory Goad files} The li ' 
resolves external references and creates relocation dictionaries 
which allow the System Loader to relocate code at load time 
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Although the APW Linker is a single program, conceptually there 
are two AP W linkers: 

D Normally, the linker is called directly by a shell command 
(such as the ASML command, which assembles and links a 
program), These commands provide a limited number of 
linker options; most linker options either are not available or 
are set to default values. In this manual, this aspect of the linker 
is referred to as the standard linker. 

□ Alternatively, all functions of the APW Linker can be controlled 
by compiling a file of linker commands. The linker command 
language, called LinkEd, allows you to do such things as place 
specific object-file segments in specific load-file segments, 
create dynamic load segments, set load addresses for 
nonreloca table code, search libraries, and control the output 
printed by the linker. You can compile and execute LinkEd 
commands separately from your source code by using the 
ASSEMBLE, COMPILE, or ALINK commands of the APW Shell. 
In this manual, the aspect of the linker controlled by LinkEd 
files is referred to as the advanced linker. 

The advanced linker is provided for programmers who require 
maximum flexibility from the system; for most purposes, the 
standard linker is completely adequate. When a statement in this 
book applies equally to the standard and advanced aspects of the 
APW Linker, the terms APW Linker or linker are used. 

Because all Apple IIGS Programmer's Workshop assemblers and 
compilers create object code that conforms to the same format, 
the APW Linker can link together object files written in any 
combination of the development-environment languages. 



Utility programs 

The Apple IIGS Programmer's Workshop includes several 
programs, called APW Utilities, that perform functions not built 
into the shell. Utilities include the following. 

■ Compact, which makes load files more compact so they load 
faster and take up less space on disk. 

■ Crunch, which combines multiple object files created by partial 
assemblies or compiles into a single object file. 

■ Dump OBJ, which lists an object-module -format file to standard 
output (usually the screen). 
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Pre DOS a binary fies are 
executable srqndaro'-App.'s II 
programs, 



* SX&ZK which pmifr two Sfes or directories for equality of 
their contents, dales, md file types. 

■ Files, which mt the contents of a director*, including 

**4nap3* nj e3 trf aiso srarch fb , a fiJe ^^ * 

contains a string you specify. 

■ init, which Jniti alizes (formats) a disk. 

- MacGcn, ^iefe generates a custom macro file, for a program. 

" Ss^fe whidi creates a ProIXtt 6 binary flte from a. I'roL 
10 los a hie. 

- Makt-LIb, wiLich creak:* a iibriry file from objeafile.s or 
modifies an existing libra ry file. 



Ihe Apple figs Debugger Is 
documented In \UoApph fes 
Debugger fefersnea 



Apple jigs Debugger 

To facilitate the debugging of programs, Apple provides a 

neS er m 1 1?** w ' :th * m ***** code ' «" *** ^ 

X* * " ""* ° f t0 eXCa,[e ' he PKWM « fall ^ecd; in 
e^er case, you can mserc breakpoints at winch the debater Ml 
cxecuuon so that ^ can inspect Eh e , OQ[ents ^ gg*i 
memory, direct page, and stack. "-ywers, 

screen, ,nc hjdlng a d.sassembiy of the code being traced (he 

App 'l c' S£S ! J"******* *** »*? life «JS& 
Appje ffig registers, and Lhc contents of the program's stack. 

because the dch.gger can provide only an assembly^ nguase 
mm of machine code, it is m m USehj ! for debuggU ™„* 
wnUen in assembly language. However, if yon We fgood ^ 
understanding of how your high-level-language program % 
conned ,nto machine code, you can us,: the the JS^gL to 
help find the subroul ine containing the problem. ** 

* A^ The Apple ilCS Debugger is noi pari of APW ft is a 
separate product, available through ATDA, See Chapter % 
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See Chapter 9 for more 
Waf motion on the Apple 
Programmer's and Developer's 
Association 1APDA), 



Language considerations 

The APW package includes a powerful 65816 assembler. At Lhe 
time of this printing, the other languages available for APW 
include C and Pascal, The APW environment is designed 10 
support any number of programming languages; check with your 
Apple dealer and the Apple Programmer's and Developer's 
Association to find out what oiher languages are available. Before 
you purchase any language, make sure that it creates APW- 
compatible files and provides full and convenient toolbox 
support. 

One of the advantages of working with APW is that the object files 
created by any APW assembler or compiler are compatible with 
those created by any other assembler or compiler. This means 
Lhat you can link together routines written in any combination of 
APW languages to create a program. 

For example, you can write an application in a high-level language 
such as C or Pascal, in order to make it portable to other 
computers and to speed up development time. Most 
programmers find it faster to write programs in high-level 
languages than in assembly language. Once the program is 
complete, you can determine which routines run most slowly and 
then write assembly-language versions of only those routines to 
enhance the performance of the program. 

•> Parameter-passing: The exact method by which parameters are 
passed is usually of no concern to your application as long as 
you work in a single language — your language's interface 
libraries and compiler take care of all parameter passing to 
and from the toolbox and among routines. However, if you are 
writing a segmented program where parameters are passed 
between routines written in different languages, you need to 
understand the parameter-passing details of your system. See 
your language reference for futher information. 
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Object module format Is defined 
n the Apple tIGs Programmers 
Workshop Reference, 



Source files, ^objecrfjiesraTidloadTi^ 

The Apple lies uses three fundamental types of program I 
source Ales, object files, and load Hies, & 

■ Source files are ASCII files consisting of code and data, I 
follow the conventions of a particular programming lang 

■ Object files are binary files created by assemblers and 

deX T' Y repreSem 3n interme diate step in the program- 
developmem process Object files cannot be read and 
modified like source files; neither can they be loaded bv the 

hies) are used only as input to the linker. 

' £ ll^?K f \ bin c ary f ' ICS Cre3ted by ,he linker - L °^ file, can 

to tL ft V ? e SyStem L ° ader ^ ey Cannot be u ^ as input 
to the finker; if you want to link a new routine to a program 
must go back to the object files to do so. 

There is a single binary file format used by APW and the An 

OmfTTJ 1 * T em: the AppIe IIGS ob > ect ™<^ fonaat 
COMF). Although OMP defines the structure and record^pL of 

i°S^ ! ° ad fQeS - do n « «« *« -pressio'Tat 
object and load files are two versions of the same thing They 

serve different purposes and are read by different programs. 



Symbolic references and relocatable"^* 

reletences is often the only wiy to jump from one We in a 
pS" ,0° s a "°"r ? r^ '"^ " *» 5 " »d, „ 
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Absoiule code, relocatable 
code, and the process of 

relocation by the System Loader 
are discussed In more detail In 
Chapters. 



The code created by an APW compiler normally contains no 
absolute references, and so need not be loaded into a specific 
location in memory. It is referred to as relocatable. Note that this 
term is somewhat misleading: a relocatable program can be 
loaded into any location in memory, but it cannot necessarily be 
moved once it has been loaded. 

The term relocation in this context means the process of 
inserting into the program in memory Cor patching) the actual 
memory addresses to which jumps must be made. Relocation on 
the Apple IIGS is done during program load by the System 
Loader. 

When source code is assembled or compiledj it is converted into 
object code containing machine -language instructions, data, and 
symbolic references. Before the program is actually run, the 
symbolic references must be resolved — they must be replaced 
with code that the loader can use to patch in the proper addresses 
at load time. The program that resolves the symbolic references is 
the APW Linker, (The linker gets its name from the fact that it can 
combine, or link together, several object files to create a single 
load file.) 



Do not write absolute code 

The advantages of using relocatable code for the Apple IIGS are 
considerable. Relocatable code can be placed in memory at 
whatever location the Memory Manager chooses. Because desk 
accessories, shell programs, RAM-based tool sets, and so on are 
placed in memory by the System Loader and Memory Manager, 
absolute code is likely to conflict with other code already in 
memory. It is very unlikely that your program will have sole 
control of the computer when it executes. 

Object module format exists primarily as a specification for 
relocatable, segmented code. The Apple IIGS System Loader and 
the Memory Manager are designed to support relocatable code. 
The APW Assembler and compilers are all designed to generate 
relocatable code. It is easy to write relocatable code. Do not write 
absolute code. 
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Four steps to creating a program 

The conversion of a source file into an executable program 
loaded in memory is done in four main steps, as follows (and 
shown in Figure 7-2): 

1. You create one or more source files with a text editor, m this J 
you design Lhe program, create its data structures, and write its] 
routines. The source filets) may be in one or more APW knguJ 

2 You assemble or compile each source file. Depending on the! 
programming language used in Lhe source file, the APW 
Assembler, C Compiler, or some other assembler or compile; 
processes the source file to create one or more object files [Tie 
object files contain 65816 machine-language instructions, dstaj 
and symbolic references to program routines. 

Object files, then, consist of machine-language instructions pi J 
unresolved symbolic references. 

3. You link the object files, using the APW linker. The linker coral 
bines all of the object files into a single load file and resolves I 
symbolic references. The linker verifies that every routine referl 
enced is included in the load file; if there are any routines thai 
linker has not found when it has finished processing all of the j 
object files, then it searches through any available library files for 
the rmssing routines. The linker replaces symbolic references with 
enu-jes m special tables it creates, called relocation dictionaries. 
The load file, then, consists of blocks of machine-language codj 
that can be loaded directly into memory (called memory 
Images), plus relocation dictionaries that contain the 
information necessary to patch address references when the 
program is loaded into memory. 

4 You execute the load file. It is loaded into memory by the 
System Loader. The loader calls the Apple lies Memory 
Manager to request blocks of memory for the load file loads 
the memory images, and uses the relocation dictionaries to 
patch the actual memory addresses into the machine-language 
code in memory, 

♦ Segments: The entire load file is not necessarily loaded into 
memory at one lime; all OMF files are divided into segments 
which can be processed independently. OMF file segmentation 
is a fundamental Apple IIGS concept— what segments are is 
discussed m Chapters 1 and 6; how to create them is 
considered next. 
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Figure 7-2 

Creating an executable Apple Ifes program 
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Segments 

When you write a program, it is generally considered good 
programming practice to divide the source code up into smaller 
units called subroutines. Subroutines make the program easier to 
write, read, and modify, 

Similarly, it is easier to link a program if ihe object files are 
divided up into smaller units. In this case, we call the units object 
segments. 

Load files, too, can be easier to load into memory if divided into 
smaller units. The subunits of load files are called load segr, 

Important Although it Is sometimes convenient to use the same or related 

divisions for subroutines, object segments, and load segments. It Is 
Important to keep In mind that they need not correspond, An abject 
segment can contain one to many subroutines, and a Eoad 
segment can contain on© to many object segments. 

The proper use of subroutines (source-code segments) is a subject 
for another book. How to create object segments and load 
segments by using APW is discussed in the following sections. 



Defining object segments 

Each APW language provides some means for specifying in your 
source file the subroutines that will go into each object segment, 
and the name of the object segment. In some languages, such as 
APW Assembly Language, you can specify the start and end for 
each object segment and can include any number of subroutines 
within the segment. In some languages, such as APW C, each 
subroutine becomes an object segment and the object segment 
name is the same as the subroutine name. 

Figure 7-3 illustrates the conversion of source-file divisions into 
object segments 



230 Chapter 7: Creating a Segmented Application 




Source file 



Object file 



Segment name: main 



Segment name: dave 



Segment name: bill 



Segment name: PAUL 



Segment name: end 



0< 



object segment 


MAIN 


object segment 


DAVE 


object segment 


BILL 


object segment 


PAUL 


object segment 


EHD 



Figure 7-3 

Assigning abject segments in your source cod© 



About load segments 

The APW Linker creates load files from object files and library 
files. The linker cannot extract from an object file a portion of 
code smaller than an object segment. So, to the linker, the object 
segment is the fundamental unit of an object or library file. The 
load file consists of one or more load segments, each of which is 
loaded into memory separately. So, to the System Loader, the 
load segment is the fundamental unit of a load file. 

Keep in mind that object segments and load segments are 
different entities, When you link a program, you tell the linker into 
which load segment you want each object segment to go. You can 
assign any number of object segments to the same load segment. 
You can assign each object segment to its own load segment, 
place the entire program into a single load segment, or anything 
in between, 
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How many load segments? 

It is not generally necessary or desirable to divide a load file I 
into too many pieces, as the loader must handle each load 
segment independendy. For small programs, in fact, you mayi 
to have a single load segment. 

On the other hand, it is often desirable to have more than on 
load segment. Because two consecutive load segments do no 
have to be loaded into contiguous memory locations, a 
segmented program may load into memory when a 
nonsegmemed program won't fit. In fact, it is necessary to 
segment some programs, because the 65816 processor does 
allow single blocks of program code larger than 64K to be load 
(there is no such restriction on blocks of data). Programs 
consist of segmented load files can often be started up more 
quickly than unsegmentcd programs because not all the bad 
segments have to be processed during the initial load. Some 
segments can be left on disk until they are needed (if ever). 

What is the optimum number of load segments for a prograd 
Only you can answer this question for your own program. Ifitisj 
small program, all of which must be in memory for the progrs 
to run, a single load segment might be fine. If the program is It 
enough that machines with smaller amounts of memory might 
have trouble loading it, several smaller segments might be betK 
Fortunately, you can segment your load file during the Jink stag 
of program development; if you are not sure how many load 
segments will be best, you do not have to make the decision - 
you are writing the source code. 

Which segments should be dynamic? 

When you specify load segments, you can designate some as 
dynamic. A dynamic segment is loaded automatically by the 
loader and Memory Manager when it is needed during prog 
execution. A segment that is not dynamic is referred to as st 
static segment is loaded at program boot time and is never 
unloaded or moved during execution 
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Overlay* are program segments 
that are alternately loaded at 
exactly the same memory 
address, No two overlay 
t&gments con be In memory at 
the sometime, and no other 
program can use that memory 
range. 



When the System Loader first loads a program, it loads all the 
program's static segments and then passes control to the 
program. When any part of the program references a routine in a 
dynamic segments, the loader finds the dynamic segment on disk 
and loads it. The dynamic segment then remains in memory for 
as long as the program is running, unless the program unloads the 
segment with a System Loader call. Unloading a segment makes its 
memory block purgeable, so the Memory Manager can remove 
the segment from memory if it needs space to load some other 
segment. 

One segment of every program — the program's main 
routine — must be static. Any other segments may also be static, 
but (especially for large programs) the system will run more 
efficiently if infrequently used segments are dynamic. There are 
several advantages to designating a segment as dynamic. Because 
dynamic segments are not loaded until they are needed, for 
example, the initial load of a program is faster if some of the 
segments are dynamic, Also, if there is a possibility that the 
computer will run out of memory while your program is running, 
you can use dynamic segments to allow several parts of the 
program to share the same portion of memory. 

When dynamic segments share the same general area of memory, 
they are similar to overlays. However, dynamic segments are 
much more versatile than overlays, because dynamic segments 
(assuming they are also relocatable) can be loaded at any 
location in memory when needed. Furthermore, one segment 
need not be removed from memory to load the next. A dynamic 
segment that is not being used is removed (purged by the 
Memory Manager) only if the application permits it (with an 
unload call), and only if the memory is needed for something 
else. Otherwise, the segment remains in memory and need not be 
reloaded the next time it is called. 

For large programs, you will probably want to see what difference 
it makes to designate a particular segment as dynamic. Sometimes, 
for example, it may be more desirable to accept a delay in the 
initial load of a program than to have the program pause while it 
loads a dynamic segment during execution. 
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To try out a segment as both static and dynamic you can eifl 

advanced Imkcr when you link the file. Most Wlan B u M «ta 
You specify in the source file that a particul rTcTd egZ ft 

tuTtoJTeT ° n the other hand - tf *™ "* "* « 

asin^/^ S rGC ° mpile lhe P r °S ram to ^ang e the t™, 

a single segment. Either way, you do ^ when * >£' 

segments, as described next. specify ic 



iinitEd. the standard linker, and 
the advanced linker ore 
dtfeussed under 'Apple I/gs 
Programmer's Workshop," eaf | ie , 
In this chapter. 



Assigning load segments in your source code" 

You can assign abject segments to load segments with source 
source-code load-segment assignments, you can always override 

£3KET Iink Ume by using a ™ fiIe " 

In AJPW Assembly Language, for example, the beginning of each I 

can we these dmcctives to specify the name of the load see™ 
o wh,ch each object segment should be assigned by DU 2 C 
load segment name in the operand field of iKetfET* 

t*T ?' ° n lhe °' her h3nd ' each funcii ™ * an object sea 

cti^:ZT e " ™2 " lHe ° bJeCt -ement ; na m :^, 
case, you use the segment directive to indicate the starr rf, T, 

are put into a single unnamed load segment. 
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Ammbfy-iongmage source file 


NRIN START SETUP 




END 






DAVE START 




END 


Bill START SETUP 




■ 


i ^ 


END 




PAUL DATA SECOND 




END 




END START 




= ^= 


END 



Object fife 

Object segment ma: n 

Load segment name. 



Object segment dave 
Load segment name: 



Obj e ct seg ment B I LL 

Load segment name: SETTJI 



Object segment paul 

Load segment name: second 



Object segment end 

Load segment name: 





Load tile 






Segment setoe 


r > 


—+- 


Standard 
linker 


S 




Segment 




S 




Segment second 


V J 







Figure 7-4 

Assigning joad segments in your source code 

If you use Lhe standard linker Ghat is, if you do no I use a LinkEd 
file), lhe source-code load-segment assignments are used when 
you link lhe file. Object segments assigned to the same load 
segment need not be contiguous in the source file; in fact, they do 
not even have to be in the same source file, The linker places all 
of the object segments that have the same load segment name 
inio the same load segment. 

<* Order of segments: The order in which the linker finds the load 
segment names in lhe source file is the order in which it places 
the load segments in the load file. If the order of the load 
segments in your load file is important, then you must either 
order your source code accordingly, or use a LinkEd file to link 
the program. 

The advantage of the standard linker over the advanced linker is 
that the standard linker is quite automatic You do not have to list 
cither the object segments or the load segments in the link 
command. Library files in the APW library prefix are searched 
automatically, and you can specify any other library files you wish. 
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Initialization segments and direct- 
pagg stack segments are 
discussed in Chapter 6. 



But there are some disadvantages to the standard linker: 

□ You must alter the source code to alter load-segment 
assignments. 

□ Some AP W languages may not allow you to assign special load 
segment types (such as initialization segments or direct- 
page/stack segments) in the source code. 

□ All of the object segments in ihe source code are linked, 
whether you want to include them in the load file or not. 

If any of these restrictions cause a problem for you, you can i 
the advanced linker to link the file, as described next. 



Assigning load segments with a LinkEd file 

The APW Linker can recognize both the names of the abject 
segments in an object file and the names of the load segments G 
any) to which those object segments are assigned. You can i 
LinkEd file to take advantage of this fact. 

For example, suppose you have written, compiled, and linked; 
program (using the standard linker), and you find that one la 
segment is larger than 64K. Because no single block of code In 
than 64 K can be loaded into memory, you must break this lo 
segment into smaller pieces. Rather than changing the load 
segment assignments in the source code and recompiling the 
program, you can link the program with the advanced linker, using' 
LinkEd commands to specify the names of load segments andtht 
object segments that go into each load segment. 

Figure 7-5 illustrates ibis process. Note that the object file is 
identical to the object file in Figures 7-3 and 7-4. Let's assume that 
the unnamed load segment is too large. By using a LinkEd file, you] 
place object segments dave and END into separate load segments,] 
named NANCY and LAST, respectively. The code in object 
segment END has been put at the end of the program. Therefa_ 
we have accomplished two things by using the advanced linkers 
have split one large load segment into two smaller load segme 
and we have changed the order in which the code appears in \ 
load file. 
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^r more derails on the standard 
ind advanced linkers, see the 
*pp/e WS3 Programmer's 
Workshop Reference 



Object file 



Object segment 

Load segment name: setup 



Object segment 
Load segment name: 



□ AVI 



Object segment bill 

Load segment name, setup 



O bject segme nt p w l 

Load segment name: second 



Object segment EMC 

Load segment name: 





Load file 






Segment setup 


A 


— *■ 

/ 


Advanced 


Segment nancy 


linker 


Segment sheryl 


Segment LAST 



Flour© 7-5 

Assigning load segments with the advanced linker 

The advanced linker gives you the freedom to ignore source-file 
toad-segment assignments and to specify into which load segment 
each object segment should go. It also lets you specify special 
segment types for load segments, and the filename and Tile type 
of the output file. On the other hand, you must specify each object 
file to be included and each object segment to go into each load 
segment. 

For small programs with only a few object segments or for larger 
programs with a simple load-file structure, the standard linker is 
easier to use. If you are developing a large program with many 
dynamic segments or with special segments such as a direct- 
page/stack segment or initialization segments, the advanced linker 
gives you much more flexibility. By changing the UnkEd file, yon 
can change the number and sequence of load segments, the 
object files and object segments linked, and the segment types ot 
load segments. For such a program, it is well worth the time and 
effort to learn how to use the LinkEd commands and to write a 
UnkEd file. 
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* Note: In using dynamic segments, it is important that the 
volumes containing all needed segments and libraries be on 
line at run lime. If the System Loader cannot find a dynamic 
segment it needs to load, execution halts and the user is 
requested to mount the proper volume. 



A global symbol Js a label In one 

segment that con be referenced 
In another segment, 05 opposed 
to a focal symbol which can be 
used only within the segment In 

wh ch il ;s denned 



Library files 

Library files are object files whose segments contain routines 
useful to many different programs. In APW, all library files are I 
object module format, regardless of the language of the source 
file. An Apple IIGS library file (ProDQS filetype $B2) can 
therefore be used by a program written in any source language. 
Some languages, such as APW C, come with a set of library files 
used by that language. 

A library file includes a special segment at the beginning of the 
file, called the library dictionary segment The library 
dictionary segment is the first segment of a library file; it coata 
the names and locations of all the global symbols in the file. 
The linker uses the library dictionary segment to find the 
segments it needs. 

When the linker processes one or more object files and cannot 
resolve a symbolic reference, it assumes that it is a reference to : 
segment in a library file. If you use the standard linker, it 
automatical iy searches all of the files in the APW library prefix 
(prefix number /2— usually volume/ APW /LIBRARIES / , where 
volume is the volume name of your boot disk) as well as any 
library files you specify on the command line. If you use the 
advanced linker (that is. if you use a LinkEd command file), the 
linker searches only the library files thai you specify. Unless you 
are using the advanced linker, you do not even need to know the 
names of the library files in order to use them; the standard Jinl 
automatically finds ihc files and extracts the segments it needs 



Creating library files 

You can create your own library files from one or more object 
files by using the APW utility program MakeLib. Figure 7-6 
illustrates the library-file creation process. You specify one or 
more object files to be included in the library file. MakeLib 
concatenates the files and creates the library dictionary segment 
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The library dictionary segment makes it possible for the linker to 
search a library file for global symbols (the names of the 
subroutines it contains) much more rapidly than it can search an 
object file. Consequently, the linker will search a library 
dictionary segment several times if necessary to find segments 
referenced by other segments in the library file, and the 
sequential order of the segments in a library file is not important. 
But if you use several library files, the order in which the files 
occur is important because each is processed only once. It is for 
that reason that MakcLib allows you to include several object files 
in a single library file, 



ObiectFile 1 



Figure 7-6 
Creating a library file 
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MakeUb is described In detail in 

the Apple IIgs Programmer's 
Workshop Reference 



In addition to creating library files, the MakeUb utility allows you 
to modify existing library files, and even to recreate an object file 
that was a component of a library file. 



Creating segmented code: three 
examples 

This section presents examples of segmented programs. Three 
small program examples are provided: a program consisting of a 
single, static load segment; a program containing several static 
load segments; and a program using dynamic segments. 
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MAIN 



I 



♦ Note: These examples are simple, text-based sample programs 
meant only to illustrate segmentation concepts. Your program* 
whether segmented or not, should be event-driven, deskti 
style applications. 




\ 

roe of 



KEEP 


HELLO 


MCOPY 


2/AINCLUDE/M16..UTIL 


START 




PHK 




PLB 




WRITELN 


# "Hello world! ■ 


Ltih 


#0 


RTL 





A single, sfatic load segment 

The following is a typical sequence for writing, compiling, and 
linking a simple one-segment program. It has only one STA 
directive, so only one segment is created. The segment is n 
explicitly made dynamic, so it is static. 

1. Boot APW and set the system language to the language type 
the source code you intend to write. We are going to write 
simple assembly-language file for this example, so enter 
following command: 

ASM65B1G 

Z Set the default prefix to the subdirectory you want to use i 
your files. If your work disk is called /MY&rogs, for exampk 
enter the following command: 

PREFIX /KYPR0G5 

3. Open a file for editing. We will call our source file HW, Enter the 
following command; 

EDIT KH 

4 Write die source code for your program. For our example, I 
in the following program: 



Output filename 
Macro file 

Beginning of segment 
Set data bank equal 

to cade bank 
Macro that writes string 
Set error code to 
Return to shell 
End of segment 
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5. Press Apple-Q to quit the Editor, When the Quit menu appears, 
press S to save the file to disk, then E to return to the APW 
Shell command line. 

6. To assemble, link, and execute the file HW, enter the following 
command: 

RUN HW 

The words Hello world! should appear on the screen, 
following the diagnostic output of the assembler and linker. If 
they do not, check your source Tile for errors and try again. 

7. You now have a file on your work disk called HELLO, To 
execute this program, enter HELLO from the APW Shell 
command line. 

♦ Note: This program cannot be executed from a finder or 
program launcher. It must run under APW. 



See Chapter 8 for require merits for 

shell applications, 



Several static load segments 

It is often desirable to write a program that consists of more than 
one load segment. For example, when there is no single 
contiguous block of memory large enough to load an entire 
program, the program may still be loadable if it is divided into 
several load segments. The program that follows is divided into 
three object segments, and each object segment is assigned to a 
different load segment. 

This program also illustrates a few of the basic functions that 
should be performed by any shell application before it begins to 
run: reading the User ID assigned to the program, reading the ID 
of the shell program that launched it, and checking the command 
line for parameters. This sample program merely prints this 
information to the screen; an actual application could do much 
more: 

□ It could use the User ID in calls to the Memory Manager and 
System Loader. 

□ It could use the Shell ID to determine whether it was launched 
by the shell program under which it was designed to run. For 
example, a compiler designed to run under APW might not be 
able to run under ProDOS or under another shell. 

q It could use die parameters on the command line for whatever 
purpose the shell application was created to fulfill. 
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The program listed below has three segments: two that begin i 
a START directive, and one that begins with a data directive.' 
program assembles into the object segments MAIN, Write, afid 
MSG, which arc linked into the load segments MAIN, OUTPUT, i 
LABELS, respectively. To create the program, first use the 
following commands to set the current language to 65816 
assembly language and to enter the editor: 



ASM65B1G 

EDIT SAMPLE. SRC 



Then type in the following program: 





KEEP 


SAMPLE 




MCOPY 


SAMPLE. MACROS 


MAIN 


START 


MAIN 


* 


SET UP ENVIRONMENT 




CLINE 


GEQU 
PHK 

PLB 


a 




5TA 


USER_ID 




STr 


CLINE 




STX 


CLIHE+-2 




POSHWORD 


USER ID 




PUSHLONG 


#QSERID+1 




PUSKWORQ 


#4 




_INT2KEX 






JSL 


WRITE 




FTL 




USER_ID 


ENTRY 






DS 


2 


USERID 


StfTRY 






STR 


i ■ 




END 





Start segment 

Sefine CLINE as direct page 
Set data bank register equal to 

program bank register 
Accumulator holds User ID 
X and Y registers contain 

pointers to command line 
Convert User ID to 

hex number 

ASCII 

string 
Jump to next segment 



Reserve space for User ID 

Reserve space for User ID ASCII string 



WRITE START OUTPUT 

* WRITE USER ID TO SCREEN 



USING 


MSG 


PUSHLONG 


#USRMSG 


_WRITECSTRIKG 




PUSHLONG 


tUSERID 


_WRITEL1NE 




LDA 


CLINE 


ORA 


CLINE+2 



Start second segment 

Use data in data segment 
Pointer to output string 
Writes "User ID = ■ 
Pointer to User ID ASCII string 
Writes User ID, Carriage Ret 
If pointer to 

command line - 0, 
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L84 



BNE 


LBl 


PU5HL0NG 


ifXOLMSG 


_WRITECSTRING 




JSR 


LB5 


WRITE SHELL ID TO 


SCREEN 


PU5HL0NG 


#IDMSG 


_WRITECSTRING 




LDY 


#0 


LDX 


*8 


PHX 




PHY 




PDSHWQRD 


[CLINEJ ,r 


_WRITECHAR 




PLY 




PLX 




INY 




DEX 




PHX 




PHY 




CPX 


#0 


BNE 


LB2 


PLY 




PLX 




PUSHWORD 


#S0D 


_HRITECHAR 




WHITE COMMAND TO 


SCREEN 


PU5HLONG 


#COMMSG 


JJHITECSTRING 




LDY 


ITb 


PHY 




LCA 


INCLINE] ,Y 


AND 


#$007F 


CMP 


#' ' 


BEQ 


LB4 


FHfl 




JJRI7ECHAR 




PLY 




INY 




PHY 




BRA 


LB3 


PUSHWORD 


#$0D 


WRITECHAR 




WRITE PARAMETERS 


TO SCREEN 


PU5HLONG 


#PARMSG 


WRITEC5TRING 





no command line 
Pointer to output string 
Writes 'Ho command line' 
If no command line, go to end 

Pointer to output string 

Writes 'Shell ID = ' 

Use Y for offset into Shell ID 

Shell ID is 8 chars, sse X for counter 

Save X on stack 

Save ¥ on stack 

Push next letteT of shell ID on stack 

Write one char of shell ID 

Pull Y from stack 

Pull X from stack 

Increment Y 

Decrement X 

Save X on stack 

Save Y on stack 

Compare X to 

Return to LB5 if X not 

Pull Y from stack 

Pull X from stack 

Write 

Carriage Return 

Pointer to output string 

Writes 'Command is ' 

Use Y for offset into command line 

Save Y on stack 

Load next character into accumulator 

Just look a t low 7 bits 

Test for Space character 

stop after first space 

Push next letter of command on stack 

Write one char of command string 

Pull Y from stack 

Increment Y 

Save Y on stack 

Return to LB3 

Carriage Return 



Pointer to output string 
Writes 'Parameters are' 
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LB 6 



LB7 
LB5 



PLY 

INY 
LDA 
AND 

BEQ 
PHY 

PHA 

_HRITECHAR 

PLY 

INY 

BRA 

PUSHWORD 

_WRITECflAR 

LDA 

RTL 

END 



[CLINEJ, r 

#S00FF 

LB7 



LB 6 
fSOD 

40 



Pull ¥ from stack 

Increment Y 

Load next character into accumulator 

Test for Null 

Stop after Null 

Save Y on stack 

Push next letter of parameters on stac 

Write one char of parameters 

Pull Y from stack 

Increment Y 

Return to LBS 

Carriage Return 

Set return code to 

Saturn to segment Main to end routine 

End of segment 



MSG 
IDHSG 

USRM5G 
COMM.SG 
PARMSG 
NQLMSG 



DATA 

DC 

DC 

DC 

DC 

DC 

END 



LABELS Begin data segment 

C'Shell ID is: '.H'OO' 

C'Dser ID is: ^H'OO" 

H" 0A* , c Command is: ' ,U"QQ' 

H'GA' ..C Parameters are; ' ,H'00' 

C'Mo Command Line . ' , H ' 00 ■ 

End data segment 



Press Apple-Q to quit the Editor. When the Quit menu appears, 
press S to save the file to disk, then E to return Lo the APW Shell 
command line. 

The program uses macros in several places, including macros for 
calls to the Integer Math Tool Set and the Text Tool Set. Execute 
the following command to create a macro file for the program: 

MACGES SAMPLE. SRC SAMPLE. MACROS 3MIHCLUDE/M16 .TEXTTOOL 2/MITCLUDE/Mlfi DTIL 
2/AINCLUDE/M1G.INTMATH 

To assemble and link the program, use this command: 

ASML SAMPLE 

To run the program, enter this command: 

SfiMPLE ONE TWO BUCKLE MY SHOE 
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The output should look Like this (the actual User ID will vary, as a 
new one is assigned each time the program is run): 



User ID is: 


112 9 


Shell in I*: 


BYTEWRK5 


Command 13: 


SAMPLE 



Parameters are: ONE TWO BUCKLE MY SHOE 



Dynamic segments 

As an example °f * program with dynamic segments, we can take 
the same multisegment example we just created and make one 
segment dynamic. What's more, we won't have to rewrite a single 
line oF the program's code or re-assemble it to do so. 

To make the second segment of the program dynamic, you can 
link the program with a LinkEd file. First, if you have not done so 
already, assemble the program (without linking it) with the 
following command: 

ASSEMBLE SAMPLE 

Use the following commands to set the current language to the 
LinkEd language and to enter the editor: 

LINKED 

EDIT SAMPLE. LINK 

Type in the following LinkEd program: 

KEEP SAMPLE 

SEGMENT MAIN 

SELECT/SCAN SAMPLE. STD (MAIN) 

SEGMENT/DYNAMIC OUTPUT 

SELECT/SCAN SAMPLE. STD (WRITE) 

SEGMENT LABELS 

SELECT/SCAN SAMPLE. STD (MSG) 

Press Applc-Q to quit ihe Editor. When the Quit menu appears, 
press S to save the file 10 disk, then E to return to the APW Shell 
command line. 

Execute the following command to link the program: 

ALIfvK SAMPLE. LINK 
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Classic desk accessories are 
described under "Supporting 

Other Desktop Features' In 
Chapters. 



The APW Linker executes this LinkEd file. Each SEGMENT 
command starts a new load segment. Each SELECT/SCAN 
command scans through the files with the root filename 
SAMPLE . STD for the object segment named in parentheses. Tl^ 
load segment OUTPUT is dynamic. The load file, sample, 
contains four segments; the fourth load segment is the Segment 
Jump Table, created by the linker. 

When you launch this version of SAMPLE, the first and third 
segments are loaded immediately, but the second segment is not 
loaded as part of the initial load. When the JSL to WRITE is 
executed, the loader loads the second segment. 

* Unloading: Note that, once loaded, the dynamic segment 
remains in memory throughout execution of the program. To 
make this segment available for automatic unloading by the 
Memory Manager, you must include an Unload Segment call it 
the end of the segment. 



Debugging 

A variety of software instruments exist to help you locate and 
correct errors in your Apple lies programs. Some are 
sophisticated and some are simple. Although nothing can make 
debugging easy, the more experience you gain with these aids, the 
more efficiently you can find and solve problems. 



Debugging with desk accessories 

The fact that Apple JIGS code is typically relocatable can be a 
problem during debugging. You can't control where the loader 
puts your program, and once it is in memory, you have no 
obvious way to locate it. How can you debug something you cart 
even find? 

Loader Dumper and Memory Mangier are two classic desk 
accessories (CDA's) provided with the Apple EGS Debugger 
(described later in this section). They can give you very basic, 
and thus very important, information on exactly where in 
memory all the parts of your program are. Furthermore, because 
they are desk accessories, they are instantly available from within 
your program or debugger. 
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Loader Dumper 

Loader Dumper is a classic desk accessory that permits you 10 
dump (print out) the System Loader's data structures: the Memory 
Segment Table, Pathname Table, Jump Table, Loader global 
variables, load-segment information, and other information used 
by the System Loader. 

A principal use of the Loader Dumper is to get your program's 
User ID from the Pathname Table. Then, using Memory Mangier 
(described next), you can find out where in memory all your 
program's segments are. 

Memory Mangier 

Memory Mangier is a classic desk accessory that can give you a 
listing of all allocated memory blocks with their associated User 
IDs, sizes, addresses, attributes, and other information. 

Most commonly, you would use Memory Mangier to inspect all 
your programs 1 segments and buffers in memory. They are 
identified by User ID, which you might have obtained from 
running Loader Dumper. Once you have found a segment you 
want to look at more closely, you can go directly from Memory 
Mangier into the Apple llGS Debugger or into the Monitor 
program (described next), to do detailed inspection and 
debugging, 

* Note-. Memory Mangier also allows you to execute Memory 
Manager calls, so you can use it as an exerciser program, to 
practice calls before writing them into your code. Even though 
this is not a direct debugging function, it is very useful because 
you need to understand the Memory Manager well. Memory- 
management errors are among the most common and most 
elusive bugs on the Apple IIGS. 



Debugging with the Monitor program 

The Apple IIGS Monitor program is a set of ROM-based routines 
that give the user direct access to program code in memory. 
Using the Monitor, you can perform these tasks: 
□ Inspect and modify the contents of any location in memory, in 
either hexadecimal or ASCII format. 

Q Move, compare, or fill ranges of memory. 
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The Monitor program ond how to 
call it we described In the Apple 
ItGS Firmware Reference 



a Search for specified patterns in memory. 

d View and change the contents of various microprocessor and 
software registers and flags. croprocessa 

1 Execute programs from within the Monitor. 
a Disassemble code in memory. 
a Use the mini-assembler to assemble small programs. 

tithTn C th e C nrr nienCe °' ^ M ° n,W ' * *" *™ ^ ^ I 
with m the program you are debugging. To do so, however ™ 

mu* make the call from bank S00, and the machine mus, fc i 

TitZZT^T *? Data Bank and Pr ^ r - = -i 

set to zero and with the direct page equal to the zero page In otl 
words, the machine must look exactly like a standard App^f 
A second method is to make a Miscellaneous Tool Set call t0 
invoke the Monitor. In this case, the machine mus b in M 
nan™ mode and the Memory Manage, must have £n sfa 
up- The call can be made from anywhere in memory^ 



The debugger Is described in 



Debugging with fhe Apple JJgs Debugged 

The Apple IICS Debugger allows you to load your program k 
memory and to run through it under the debugged coZ 
^program executes, you can examine the „S o7the 

-y lo aSTn m°e V ° Ur ^T^ ^ ™* ^ S ^4 

imerac Zl Z ^ " WWch Y ° U ™ interested ** can 

interact wiih the program as required, returning to the denuo 
d lSP Iay at breakpoints that you set, or when thf ^^ 

Slight 00 ? ° CbUi!8er "" d '^y an ^cmbly-Ianguage 

you 7c.:": c°oro r r prosrarT,,s machine code - Jt «™ ™ 

rrX Th r u rCCreaEe y0lir SOurce ct >de from machine 

code. Therefore, the debugger is easiest to use withTssTmblv 

b™ ,7 lan guage and you hare no knowledge of assembly 

ZTJ^l^CT ? bugser to **«** ^^ 

,7' ' c P^blem lies, You can also gain a better 

me stack, direct page, memory, and registers. 
We do not have the space here to examine in detail all of rt» 

a neip get you started debugging your program, 
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Debugging segmented programs 

In order to use the Apple HGS Debugger to debug a segmented 
program, you must know where in memory each segment has 
been loaded. In the case of a dynamic segment, you must know 
whether it has been loaded and, if so, where. This information is 
available through the Loader Dumper desk accessory, described 
earlier in this section. 

To load your program by using the debugger and to determine 

where in memory each segment is loaded, use the following 

procedure: 

1. Start up the debugger. 

2 Use it to load your program into memory, 

3. Call the Loader Dumper from the desk accessories menu. 

4. Use the Loader Dumper to get the User ID of your program. 

5. With that User ID, use the Loader Dumper to get a listing of all 
your program's load segments and their memory addresses. 

You now have several possible courses of action open to you. If 
you do not have any idea in which load segment your program is 
crashing, you can start by running the program until it crashes 
and then examining the debugger display to determine the 
location of the problem instruction. If you know in which segment 
the problem lies, you can go immediately to that segment, or you 
can set a breakpoint at the beginning of that segment and run the 
program until it stops automatically at that breakpoint. 

Watching a running disassembly 

If your program does noL require any input from the keyboard, 
you can watch a disassembly on the debugger screen as the 
program executes to find the exact location at which it goes 
astray This technique will probably be useful only for short 
programs or programs that crash almost immediately upon 
execution, because the program will execute very slowly while the 
debugger display is on the screen. 

To run your program under control of the Apple HGS Debugger, 
wkh a running disassembly appearing on the screen, use the 
following procedure: 

1. Load your program with the debugger, 
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2 Pul the debugger in single-step mode, starling at the first 
instruction of your program. Watch the contents of the reg 
and the stack (and any specific memory locations you have 
specified) as you execute individual commands. 

3- You can leave single-step mode and execute commands 
automatically in quick succession by entering trace mode. Yo 
program will begin executing under debugger control, one 
instruction at a time in rapid succession. Once in trace mode, 
you can stop execution at any time and then return to single- 
step mode 

In trace mode, when your program executes a BRK instruction 
execution stops. The last instruction executed (the BRK 
instruction) is displayed on the screen, along with the previous 
several instructions executed, A BRK instruction is actually a null 
Ca zero byte); because such an instruction is not a normal part i " 
a program, the fact that your program executed one probably 
means that some previous instruction sent the program off to U^ 
wrong place in memory, With luck, the instruction that sent you 
program off into Mever Never land will still be on the screen. 

Using breakpoints 

If you have to interact with your program in order for it to run, if j 
you have some idea of which segment contains the bug, or if you 
just want to execute die program more quickly, you can set one ( 
more breakpoints before running the program. A breakpoint is a 
location at which the debugger suspends execution of the 
program, giving you the opportunity to examine the disasseml 
and the state of the machine at that location. 

To set breakpoints and run the program under debugger control, 
try the following procedure: 

1. Load your program with the debugger, 

2. As described above, use the Loader Dumper routine to 
determine the starting locations of the load segments of your 
program. 

3. Back in the debugger, set breakpoints at the beginning of each 
load segment (if you do not know in which segment the bug 
lies) or at the beginning of any segment that you want to 
examine more closely. 
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4, Run your program under debugger conirol, with the debugger 
display turned off. When the debugger comes to a breakpoint, 
the program halts and the debugger's display appears on the 
screen, showing the location of the instruction at which the 
program stopped and other pertinent information. You can 
also view a disassembly of the program, starling at the 
breakpoint location. 

5. While at a breakpoint you can switch to single step mode. Step 
through the segment one instruction at a time while watching 
the contents of the stack, the machine's registers, and up to 19 
memory locations you specify. From single-step mode, you can 
return to executing the program automatically. 

If at any time during execution of the program a dynamic segment 
is loaded, you can pause execution of your program and go back to 
Loader Dumper to find out where in memory it has been placed. 

Breakpoints can be used for purposes other than finding a 
particular segment. Suppose, for example, that your program 
seems to run all right for awhile, then crashes after having lulled 
you into a false expectation of success. In this case, it is possible 
that some routine is failing, not the first time it is run, but only 
after going through several iterations. To handle such a situation 
without stopping the program every time the routine is executed, 
you can include a trigger value for a breakpoint. The debugger 
counts the number of times it encounters the breakpoint, and 
suspends execution only when the trigger value is reached. 

If you must execute a routine at full speed in order for it to work 
correctly, you can insert real breakpoints into the code. When you 
do so, the debugger actually inserts BRK instructions into memory 
at the breakpoint locations. Trigger values work for real 
breakpoints that you have set; the debugger will still suspend 
execution any time it encounters a BRK instruction that you did 
not set as a breakpoint, 
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Using memory protection ranges 

It may be thai certain portions of your code must be executed at] 
the full speed of the 65816 microprocessor. To cause this r.o 
happen automatically every time you trace through the progrtflj 
you can set any areas of memory you choose as code trace 
ranges. When the program executes a jump to a location within i 
code trace range, the debugger relinquishes control to yourJ 
program and the code is executed at full speed. The portion of 
memory used to run tool calls is automatically set as a code trie 
range when you load the debugger. 

You can also set one or more portions of memory (the limits of 
your code as revealed by Loader Dumper, perhaps) as codem 
window ranges. If the program attempts to execute code outside 
the code-window ranges you have set, execution stops. You might j 
want to set a code-window range, for example, if your program is i 
executing a jump to some incorrect memory location and 
trashing memory before it stops, forcing you to reboot the 
machine every time you try to run the program with the debuj 

If your program loads a dynamic segment during execution and 
you want to pause as soon as control is transferred to the dj 
segment, you can scl code window ranges to include all the static] 
segments at die start of the program. Then when the dynamic 
segment is loaded and control is transferred to it, the program 
will be outside any code window range and execution will stop. 



Important 



One© you have set any code-window range, no code will be 
executed that is not in a code-window range. Therefore, if you sett 
code-window range equal to the memory location of one of your 
program segments, you must set code-window ranges for all other 
segments that if calls. 



Debugging multiple-language programs 

One of the advantages of using the APW development 
environment is that it allows you to link together routines written 
in different programming languages. This facility can lead to 
unique problems, however, especially when information is passed 
between routines wditen in different languages. 
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Parameter passing may fail in your program for any of several 
reasons: you might have used a wrong variable type, for example, 
or a called routine might expeel 10 receive parameters in a 
different order from the way ihey were passed by a calling routine. 

To use the Apple IIGS Debugger to debug para meter- passing 
problems, use the following procedure: 

L Set breakpoints at the beginning of the calling segment and at 
the beginning of the called segment. 

2. Run the program in trace or real-time mode until the first 
breakpoint is reached. Search this segment to find the JSL that 
calls the other segment. 

3. Set a breakpoint just before the JSL that calls the second segment. 
You can remove the other two breakpoints now if you wish. 

A. Run the program until the JSL breakpoint is reached. 

Parameters are normally passed either on the stack or in the A, 
X, and Y registers. The actual information passed may be a 
pointer to the data rather than the data itself. By examining the 
contents of the registers, the stack, and memory, determine the 
location of the parameter being passed, and see if it has the 
value you expect, 

5. Execute the JSL. The return address should have been added to 
the stack. 

6. Step through the segment in single-step mode, Is the called 
routine reading the parameters passed to it, in the proper form 
and order? By a careful study of the action of the called 
routine, you should be able to determine the source of the 
problem. 

7. If all parameters are being passed correctly, perhaps the 
problem occurs when the results are passed back to the calling 
routine, Find the RTL, and study the stack and registers as 
before to determine whether the results are being passed 
correctly back to the calling routine. 



The ProDOS 16 Exerciser Is on the 
disk that accompanies the Apple 
Slss ProDOS 16 Reference 



The ProDOS 16 Exerciser 

The ProDOS 16 Exerciser is a program that allows you to practice 
making operating system calls in a controlled environment, 
before coding ihem into your applications. 
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The ProDOS 16 Exerciser is not really a debugging tool, but you 
can use it in several ways during the debugging process. For 
example; 

□ By practicing the ProDOS 16 calls you intend to use in your 
program, you can "debug" them in the sense that you can see 
exactly how they function, before writing them into your code, 

P Because the Exerciser gives you direct access to file attribuia| 
you can use it, for example, to change file types (such as from 
$B5 to 503) without having to enter APW. 

□ The Exerciser allows you to inspect and modify the contents d 
any portion of memory, and any block on a disk — but see ite 
warning below. 

□ The Exerciser allows you to enter the Monitor program 
directly. Once in the Monitor, you can use its debugging 
facilities, as described earlier. 



Warning The ProDOS 16 Exerciser allows you unconstrained use of all ProDOS 
1 6 colls, Including those that modify disk directories and blocks, It 
also permits you to modify any portion of memory. Including that 
occupied by system software or by the Exerciser Itself. You can 
easily destroy the contents of a disk or cause a system crash, Be 
careful what you modify! 
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What Type of Program 
to Write? 
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A list of all defined file types Is 

given uncter "The ftoDOHRte 
System in Chapter 6. 



Under ProDOS 16 on the AnnJp Jh-c ™ 

classified by file ty De W S ? "™P"ter, program* , 

this chapter: ,que fi|e 'N* 8 - a "= Sfm i 

a general applies Lions (Ale type $B3) 

o coding programs, such as shells, switchers< and ^ 

D Sf-ffitfi CRJe * pe 3B5 > *« * I**™ *.m| 

O desk accessories (file types iB 8 and $B9) 

□ initialization fiJes (file types $fi6 ^ ^ 

□ interrupt handlers 

° user too1 s ^ (file type $BAJ 

anting some of the other, more special SI ^ m 

^orm^n ta this chapter cS^S"^^ * 



General applications 



-.led b b n k u r c XT ha m n e r a r pieie pr °^ m - « . 

communicate d recUv wi h * T^ Pr ° gram) ' that " n 

& needs. For e word " " ****** S ° ftWarc or fi ™4 

-de mis, a * we" rx lt^ r;r d Data f ? s and — 

accessories, and utilities that 2^35^^ ** 
are not applications. ° m other P™8«JH 
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To be a (stand-alone) application, an Apple IK3S program needs 

to meet certain requirements. Jl. must 

a consist of executable machine-] an gunge code 

r lx: in Apple IIG5 object module formal 

n have a file type of $B3 

n us<: Pin DOS 16 as its operating system 

J observe Lhti ProDOS 16 QUIT conventions 

p get all needed memory from the Memory Manager 

All other aspects of the program are up to you. But of course wi: 
Ml.rrmgly recommend that you design your progams to use the 
Apple deskiop intciface and follow the Apple Human Interface 
Guidelines. 

& l^roDOS 8: The above list, refers specifically to Apple IICS 
applications thai ri.ni under ProDOS 16, Requirements for 
programs that run under ProDOS 8 arc quite different; see the 
f->vanQS $ Technical Reference Manual 



t-'ruDOS S system pi og terns are 
described In trie ProDOS 8 
Technical Reference Manual. 



For a more detailed dcsciotlon of 
system slur I up, see? the Applo lies 



Make it seIf-boo!ing? 

There are two ways to make your type SIB application self- 
booting, so that il is automatically luatled and launched at system 
si.ani.ip: 

n Ciive it the Hie name extension . svsifi. By using this method, 
your program fafecomC,<3 a ProDOS l6 equivalent to a PrnDOS ft 
system program on a stoic itlard Apple II computer. 

D Give it the filename start and place it in the system/ 
subdirectory. By using this method, your program substitutes 
for ihe finder or program launcher that normally ex;:t:til.es first 
on the Apple URS£ 

In cither ease, your proftam must be the first (or only) program 
with the proper filename or filename extension [hat the boot 
loader program encounters on &\e, In ml. disk. Figure 8-1 diagrams 
Lire program selection sequence at system sianup. 



General applications 



257 



(Boat sequence: 

the file named 

PRO DOS Is executing!) 



is there a file nomed 
/WSYSTEM/START? 

yes 



no 



is there a .SYSTEM 
Or SVS16 file'" 1 






Which found first? 
.SYS16 file found first 



Execute a 

ProDOS16 

QUIT call. 

using the 

filename 

of the 

SYS16 

program 



C SYS 16 program executes) 



Fatal error 



.SYSTEM file found first 



Execute an 
enhanced 

ProDOS a 
QUIT call, 
using "the 
filename 
of the 
.SYSTEM 
program 



(.SYSTEM progrom executes) 



load and 
execute 






/V/SYSTEM/START 







START Is typically 

a program 
selector/finder 

Figure 8-1 

Startup program selection 

<* :\'olc: Apple recommends that you do not name your 

application START— leave that name for a program launcher 
or finder. If you give your program a clearly identifiable name, 
the user can more easily launch it from any boot disk. 
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The concepts of dormant and 
restartable programs are 
dscjssed under "Loading 
Frograms and Segments" In 
Chapter 6, 



For more Information on the APW 

C language, see the Apple IIG$ 
Programmer's Workshop C 
ffeterencs 



Make it restartable? 

If you want your program to be able to be quickly relaunched 
from a dormant state in memory, it needs to be restartable. A 
restartable program reinitializes all its variables each time it gains 
control, without having to read in files or segments from disk. It 
also makes no assumptions about the state of the computer, such 
as register contents or (lag settings, when it gains control. If all 
initialization information is in code statements in your program's 
initialization segments and static code segment(s), the program 
should be restartable. 

It is difficult for programs in some languages to be restartable. In 
C, for example, all global variables are in segments named 
-GLOBALS and ~ ARRAYS, which must be initialized each time the 
program starts up. To get around this difficulty, the System Loader 
supports the concept of RELOAD segments. A RELOAD segment is 
a static data segment that is loaded from disk whenever an 
(otherwise) restartable program is launched from a dormant state. 
It contains whatever initialized data is needed by the program; the 
rest of the program's static segments (other than initialization 
segments) are not loaded at that time. 

When your application quits, it passes a parameter to ProDOS 16 
(and thence to the System Loader) stating whether the application 
is restartable or not. You must determine when you write the 
program what type it really is; neither ProDOS 16 nor the System 
Loader will check. 



Progioms that run under shells or© 
cafled shell applications and ere 
fie type $85, 



Controlling programs 

A controlling program is a program that loads and executes other 
programs while itself remaining active in memory. An application 
needs to be a controlling program only if it must remain in 
memory after it calls another program. The APW Shell is a 
controlling program; ProDOS i6 is a controlling program. 

Writing a controlling program is far more involved than writing 
an application. This book does not show you how to write a 
controlling program; but if you do write one, please follow the 
guidelines below. They specify how your controlling program 
communicates with shell applications. Sec also the next section, 
"Shell Applications," for more information on how controlling 
programs and their subprograms interact. 
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ProDOS 16 register and direcf- 
page/stack conventions are 
discussed under "Setting Up 
Direct- Page/Stack Space" In 
Chapter 6, ond fully descrlbad In 
the Apple ))gs ProDOS 16 
RefQrenca 



See "Quitting and Launching 
Under RoDOS 16.* In Chapter 6. 



a Your controlling program should use the System Loader's 
Initial Load function to load Lhe subprogram. Initial Load 
returns the subprogram's starting address and User ID to yo 
controlling program. When your controlling program passe 
execution to the subprogram, it should pass the subprogram 
User ID in the accumulator. 

□ Your controlling program may also pass parameters and ill 
identifier string lo the subprogram, as described under "Shq| 
Applications." 

d Your controlling program is responsible for establishing the 
appropriate input and output vectors for its subprograms. FO 
example, when ProDOS 16 launches a program, it initializes 
Text Tool Set to use the Pascal I/O drivers for the keyboard j 
and 80-column screen. 

□ Unless all its subprograms include direct-page/stack segmer 
your controlling program must provide a default direct- 
page/stack space for any subprogram that it launches. The 
controlling program should observe the ProDOS 16 
conventions for register initialization and direct-page/stack 
allocation, 

□ Shell applications can terminate with either an RTL instruc 
or a ProDOS 16 QUIT call, If any of its subprograms might i 
QUIT, your controlling program must intercept all ProDOS 
calls so that when the subprogram quits, the controlling 
program, rather than ProDOS 16, regains control. 

n Your controlling program is totally responsible for dispc 
of the subprogram. When the subprogram is finished, the 
controlling program must remove it from memory and releat 
all memory resources associated with iLs User ID. The best i 
to do this is to call the System Loader's User Shutdown 
function. If the program ends in a QUIT call, your control! 
program is responsible for performing any other system task 
normally done by ProDOS 16 in response to a QUIT. 
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See 'Loading Programs and 

Segment*' In Chapter 6 for a 
cflicussion of controlling 
programs and the System 
Loader's Initial Load function. 



See an example of reading an 
identifier string in the second 
samplB program under "Creating 
Segmented Code: Three 
Examples* In Chapter 7. 



Shell applications 

Shell applications (ProDOS 16 file type $B5) are executable load 
files ihat are run under a controlling program such as the APW 
Shell. The controlling program launches the shell application by 
calling the System Loader's Initial Load function, and transfers 
control to the shell application by means of a JSL instruction, 
rather than launching the program through the ProDOS 16 QUIT 
function. Therefore the shell does not shut down, and the 
program can use shell facilities during execution. 

A shell application typically returns control to its shell with an 
RTL instruction. With a shell (such as the APW Shell) that 
intercepts ProDOS 1(5 calls, the shell application can end with a 
ProDOS 16 QUIT call. 

Shell applications should use standard Text Tool Set calls for all 
nongraphics I/O; the controlling program is responsible for 
initializing the Tex i Tool Set routines. 

♦ Stand-alone: A shell application can run alone under ProDOS 
lfj if it requires no support other than standard input from the 
keyboard and output to the screen, ProDOS \6 initializes the 
Text Tool Set to use the Pascal I/O drivers (discussed in the 
Apple tIGS Toolbox Reference} for the keyboard and 80- 
column screen. To be launched this way, a program must first 
be changed to file type $B3, and it must end with a ProDOS 16 
QUIT call. 

As soon as a shell application is launched, it should save the value 
of its User ID, passed in the accumulator from the controlling 
program. It should also check the X and Y registers for a pointer 
to the she II -identifier string and input line. The X register holds 
the high-order word and the Y register holds the low-order word 
of this pointer. The controlling program is responsible for 
loading this pointer into the index registers and for placing the 
following information in the area pointed to: 

a An 8-byte ASCII sLring containing an identifier for the shell. 
The identifier for the APW Shell, for example, is BYTEWRKS. 
The shell application should check this identifier to make sure 
that it has been launched by the correct shell, so that the 
environment it needs is in place. If the shell identifier is not 
correct, the shell application should write an error message to 
standard error output (normally the screen), and exit with a 
ProDOS 16 QUIT call (if the controlling program supports it) 
or an RTL. 
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For more information on direct 
page and stack ailocaflon, see 
"Setting up Direct- Page/Stock 
Space* in Chapter 6, See also the 
Apple iigs ProDOS }6 Refeienca 



□ A null-terminated ASCII string containing the input line fori 
shell application. The shell can strip ar) y I/O redirection or 
pipeline commands from the input line, because those 
commands are intended for the shell itself, but must pass 
mput parameters intended Tor the shell application, 

* ProDOS 16: ProDOS 16 does not support the identifier sta 
or mput line convention. When an application is launched! 
ProDOS 16, the X and Y registers contain zeros. 

If the shell application does not have a direct-page/stack segn 
it can expect the controlling program to provide a 1024-byte 
memory block in bank $00 for the shell application to use for ft 
direct page and stack. Whether the shell application specifies a 
dircct-page/stack segment or accepts the default, the address < 
the start of the dircct-p age/stack segment should be in the dirt 
register <D). and the stack pointer (S register) should point to I 
last Oi.ghest-address) byte of the block containing the direct- 
page/stack segment. 

Some shell applications may launch other programs; for exams 
a shell nested within another shell would be a controlling 
program as well as a shell application. Such an application must 
follow the conventions for both types of programs. 

A shell application should use the following procedure to quit: 
1. If the shell application has requested any memory buffers it 
must release (dispose of) them, 

2 The shell application should place an error code in the 
accumulator. If no error occurred, the code should be SOOOQ 
The code $FFFF can be used as a general (nonspecific) error 
code. Other error codes are up to the controlling program to 
define and handle, 

3. The shell application should execute an KTL or if the shell 
supports it, a ProDOS 1 6 QUIT call. 



Desk accessories 

A desk accessory is a small program that a user can run without 
closing down an already-running application. The Apple IIGS 
supports two different kinds of desk accessories: 
■ Classic desk accessories (CDA'S) are designed to execute in i 

non-desktop environment, The CDA interrupts the applicatic 

and gets full control of the computer. 
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■ New desk accessories (NDA'S), on the other hand, are designed 
to execute in a desktop environment. As such, Lhey operate in a 
window and arc subject to the same rules as an event-driven 
application. They are not stand-alone applications, however, 
because they rely upon another application to start up the 
Apple IIGS tools. 

Neither type of desk accessory has a lot of extra programming 
overhead apart from the actual task the accessory performs. Both 
types depend heavily for support upon the Apple IIGS tool set 
called the Desk Manager. 



Writing classic desk accessories 

A classic desk accessory must start with a header consisting of a 
name suing, a pointer to the start of the code, and a pointer to 
the shutdown routine. 



StartofCDA 



str'Name of DA' 

dc 14 ' StartOfDACode' 

dc ±4 'ShUtDownRoutine' 



DA name (this is an APW macro) 
Pointer to start of code 
Pointer to shutdown routine 



When a CD A gets control from the Desk Manager, the processor 
is in full native mode. Because the Desk Manager has already 
saved the necessary pans of the old environment, the CDA can 
concern itself solely with its own work. 

A CDA follows this basic procedure: 

1. It initialises for the machine environment it needs. The Desk 
Manager has already saved the old state when the CDA gets 
control, 

2. It does the actual work of the CDA. Like all Apple IIGS 
applications, a CDA should ask the Memory Manager for any 
space that it needs. In addition, the CDA must leave the stack as 
it was when the CDA got control. 

3. It returns to the Desk Manager with an RTL, 'Hie Desk Manager 
then automatically restores the old state and returns to the desk 
accessory menu. 

Every CDA must have a shutdown routine. The shutdown routine 
is called every lime the Desk Manager shuts down. 

Classic desk accessories have die Pro DOS file type $E9. On disk, 
they must be in the DESK, ACCS/ subdirectory of the SYSTEM/ 
directory. 
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Writing new desk accessories 

AJl new desk accessories are loaded from the disk at boot . 
When an KDA gets control from the Desk Manager, the pn 
is in full native mode. By convention, the NDA can assume 
the tool sets shown in Table 8-1 have already been loaded and] 
siarted up. If the NDA needs any other tool sets, it must load 
start them up itself. 

Table 8-1 

Tool sets loaded and available to new desk accessories 



Tool set 



Tool Locator 
Memory Manager 
Miscellaneous Tool Set 
QuickDraw II 
Event Manager 
Window Manager 
Control Manager 
Menu Manager 
LineEdit Tool Set 
Dialog Manager 
Scrap Manager 

Note, The NDA may also assume that the Print Manager is available, 
although not necessarily loaded and started up 

A new desk accessory has a structure fundamentally different From 
that of a desktop application. For one thing, it has no event 
loop— it relies on the application's event loop and the Desk 
Manager to open it, prod it into action, and close it. Far another, 
it has only four nonprivate routines: ink, open, action, and dosfl 
□ The Desk Manager calls the tnit routine to initialize the NDA 
when the Desk Manager starts up, and again when it shuts down. 
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□ The Desk Manager calls the open routine when the NDA is 
selected by the user from the Apple menu. The open routine 
opens the desk accessory window and returns a pointer to it. 

□ The Desk Manager calls the action routine in response to an 
event within the NDA window, or when a specified time period 
has passed, or if a selection has been made from an NDA 
menu or the Edit menu, and in other special cases. The action 
routine performs whatever tasks the NDA was designed for. An 
action code passed in the accumulator tells the NDA why it was 
called. 

a The Desk Manager calls the close routine to close the desk 
accessory window. 

The processor is in full native mode on entry into all four 
routines. All four routines should end with an RTL instruction. 

An NDA action routine follows this basic procedure: 

1. It saves important global values, such as the application's 
current GrafPort. 

2. Based upon the action code received, it takes appropriate 
action, 

3. It restores the global values and returns to the Desk Manager 
with an RTL. 

You must start ihe NDA with an identification section that 
specifies the pointers to the four routines, the NDA's period Glow 
often it runs), its event mask (what events it wants), and its menu- 
line (text defining its title on the Apple menu). For example, the 
identification section could look like this: 



StartofNDA 



etc t4'PtrTo0pen' 

dc 14 "PtrToCiose 1 
dc i4 , PtrToflction' 

tie i4 , PtrTo!nit' 
dc 12 ■ Period' 
dc 12 'EventHssk ' 
dc c' MenuLine\H»* 
dc ll'O' 



Pointer to open routine 
Pointer to close routine 
Pointer to action routine 
Pointer to init routine 
How often to run 
What events to retrieve 
Text for menu item 
Terminator for the menu line 



New desk accessories have the ProDOS file type $B8. On disk, they 
must be in the DESK. ACCS/ subdirectory of the SYSTEM/ 
directory. 
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Initialization files 






Initialization flies are files of types $B6 and SD7, in the 
SYSTEM. setup subdirectory. They are special-purpose programs 
that perform initialization at system startup, before any 
applications have been launched. 

There are two types of initialisation files — temporary and 
permanent: 

■ Temporary initialization flies (type SB7) are loaded and 
executed just like applications ($B3), except that they must 
terminate with an RTL rather than a QUIT, lliey are removeM 
from memory when finished. 

■ Permanent initialization files (type SB6) are loaded and 
executed just like applications ($B3), except for these 

conditions: 

D They must not be in special memory. 

z. They cannot permanently allocate any direct- page/stack I 
space. 

□ They must terminate with an RTL rather than a QUIT. 

Permanent initialization files are not removed from memory 
when finished. 

With initialization files, you can customize the operating 
environment before any applications are loaded. The 
TOOL . SETUP file is an example of an initialization file; it loads 
RAM patches to tool sets. TOOL . SETUP is a permanent 
initialization file because other system software needs it during 
program execution. If your initialization files need to execute only 
once, make them temporary-. 

♦ Note; Don T t confuse these initialization files (programs 
executed at system startup) with initialization segments (pieces 
of an application executed when the application starts up). See 
"Loading Programs and Segments" in Chapter 6. 
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Interrupt handlers 

On the Apple IIGS, Interrupts may be handled at either the 
firmware or the software level. The b-uik-in interrupt handers are 
in firmware (discussed in the Apple IICS Firmware Reference); 
user-installed interrupt handlers are software and may be called 
directly by the firmware or through ProDOS 16. 

When the Interrupt Request GKQ) line on the Apple IICS 
microprocessor is activated, or when a software interrupt occurs, 
the microprocessor stops executing the current application and 
transfers control to the firmware interrupt-processing routines. 
The built-in interrupt handler processes the interrupt if the 
application has not provided its own interrupt handler, 



The built-in interrupt handler 

The Apple lies built-in interrupt handler is a firmware program thai 
performs a sequence of steps to handle system interrupts. When a 
program is interrupted, the handler saves the current state of the 
system. The handler then processes the interrupt itself or passes 
execution to another handler, either internal or external, On com- 
pletion of interrupt processing, Lhe interrupted program regains 
control and can continue as though nothing had happened. 

Figure 8-2 and the following explanation give a simplified picture 
of the steps taken by the built-in interrupt handler; they emphasize 
the course of execution when the interrupt is to be serviced by a 
user-installed handler. 

1. When an interrupt signal occurs, execution jumps indirectly 
through the interrupt vector EIRQ if running in emulation 
mode when the interrupt occurred, or NIRQ if in native mode. 

2 The system then tests to see whether the interrupt was the result 
of a software Break instruction. If it was, the system vectors to a 
break handler through a break handler vector in bank $E1. If 
no break handler is installed, execution passes through the user 
break vector at S3F0 in bank zero, which normally points to the 
Monitor program. 
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3. If the interrupt source was not a Break instruction, the inter 
handler saves the absolute minimum amount of information 
about the machine state — -just that necessary to read an 
incoming serial character- — and then tests for AppleTalk ind 
serial port interrupts. This hasty action is necessary so that 
incoming characters in high-speed transmission will not be 
lost. If the interrupt is a serial interrupt, the firmware executes^ 
JSL. instruction to the serial port handler. 

4. If the interrupt is not a serial interrupt, the interrupt handler 
saves the rest of the machine state and establishes a specific 
interrupt memory configuration, as described next under "E& 
vironment Handling for Interrupt Processing," It begins ai 
loop, testing each of the possible interrupt sources in turn. 

5. If no internal interrupt handler claims the interrupt, then (at 
only then) the firmware jumps through the user interrupt 
vector, to a user-installed routine that handles the interrupt 
The address of the user interrupt routine is found in bank $00, 
addresses $3FE (low byte) and $3FF (high byte). 
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NIRQ 
StC. 




Switch to high speed 



JSL Appleft* 

JSL Seriallnt 



(S3F0) 
Bonk SOO 



Save more state info, 
poll all other sources 
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•JSL 
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(.Usually the monitor) 



User interrupt vector 
tS3FE) In Bank $00 



Figure 8-2 

Built-in Interrupt handler (simplified) 
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Environment handling for interrupt processing 

For each type of interrupt, the processor can be in either 
emulation or native mode. The built-in interrupt handler must 
save the current environment in each case, set the interrupt 
environment, process the interrupt through the appropriate 
interrupt handler, and then restore the original environment 
before returning control to the interrupted program. 

The interrupt environment is the machine state that your inter- 
rupt handler finds when it gains control. If your handler is called 
from the user interrupt vector, the environment includes these 
conditions: 

□ emulation mode 

□ slow speed (lMH?) 

□ text page 1 switched in (main screen holes available) 

□ main memory switched in (for reading and writing) 
D $DO0O-$FFFF ROM mapped into bank $00 

D main stack and zero page switched in 

□ main stack pointer active (auxiliary stack pointer saved) 

If your handler is called through a JSL from the built-in handler 
before jumping to the user interrupt vector, the same state applies 
except that the machine is in 8-bit native mode and running at 
fast speed. 

♦ ProDOS 16: If your interrupt handler is installed through 
PRoDOS 16, the machine state it finds is somewhat different. 
See "Interrupt Handling Under ProDOS 16," later in this 
section, 

After the interrupt has been processed, the system interrupt 
handler restores the environment and registers to their 
preinterrupt state and executes an R1T (return from interrupt), 
returning to the executing program. 
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Des&jptrons and locations of all 
interrupt vectors are listed | n 
Appendix D of Apple IIgs 
Firmware Reference 



Interrupt soft switches are 
documented under "Soft 
Switches' In the>\pp/e lies 
Firmware Reference. 



Writing and installing your own interrupt handler 
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* :«r buiiNn imcrmpt hand,e ' ^ —*« » «! 
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Interrupt handling under ProDOS 16 

You can write an interrupt handler and install it under ProDOS 
16, if you wish. ProDOS 16 installs its own vector at location $00 
03FE (page 3 in bank zero), so when an interrupt occurs, execution 
passes through that location. At that point the microprocessor is 
running in emulation mode, using the standard dock speed and 8- 
bit registers, The vector at $00 03FE points to another bank zero 
location, that in turn passes control to the ProDOS 16 interrupt 
dispatcher. The interrupt dispatcher switches the processor to full 
native mode (including higher clock speed) and then polls the 
user-installed interrupt handlers. When the interrupt has been 
serviced, ProDOS 16 returns to emulation mode and passes 
control back to the built-in interrupt handler. 

Figure 8-3 is a simplified picture of what happens when a device 
generates an interrupt that is handled through a ProDOS 16 
interrupt handler, 
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ProDOS 16 supports up lo 16 user-installed interrupt handlers. 
When an interrupt occurs that is not handled by firmware, 
ProDOS 16 transfers control to each handler successively until 
one of them claims it. There is no grouping of interrupts into 
classes; their priority rankings are reflected only by the order in 
which they are polled. 

If you write an interrupt handler to run under ProDOS 16, note 
these conventions: 

□ Your handler will gain control with the machine in full native 
mode (e, m, and x = 0), with a fast clock speed. 

□ Interrupts will be disabled. Do not re-enable interrupts from 
within your interrupt handler. 

D The handler must exit with an RTL instruction. The machine 
should again be in full native mode, at fast speed. The carry 
flag must be cleared C = 0) if the interrupt was serviced, and set 
C - 1} if it was not— that is how ProDOS 16 knows whether o: 
not your handler has claimed the interrupt. 

To make your interrupt handler active, install it with the ProDOS 
16 A1LOCJNTERRUPT call. To remove it, use the DEALLOC 
INTERRUPT call. lie sure to enable the hardware generating the 
interrupt only after the routine to handle it is allocated; likewise, 
disable die hardware before the routine is deallocated. 



User tool sets 

The Apple liGS Toolbox is quite extensive and provides a great 
deal of programming convenience; there are over 800 separate 
routines that you can call from your applications. Furthermore, 
because of the flexibility of the Tool Locator system, your 
application is not restricted to even this large number of tool 
calls. In addition to the system tools (provided by Apple), you 
can write and install your own tool sets, called user tools. 

Writing and installing user tool sets is fully documented under 
"Writing Your Own Tool Set" in the Apple HGS Toolbox 
Reference. We won't repeat that information here, beyond listing 
these few main points; 
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□ The open-ended, flexible nature of the Tool Locator is what 
makes it possible lo add your own tool sets. The Tool Locator 
requires no fixed UOM location and few fixed RAM locations, 
so it may easily modify its data structures to incorporate new 
tool sets. 

D Each tool set is assigned a permanent tool number. System 
tools are assigned numbers by Apple; you can assign your own 
numbers lo user tool sets that you create. Assignment starts at 1 
and continues as successive integers (2, 3, 4, and so forth). 
Table 8-2 lists the presently defined system tool numbers. 



Table B-2 






Tool sot numbers 




Hexadecimal 


Decimal 


Name 


SOI 


1 


Tool Locator 


$02 


2 


Memory Manager 


$03 


3 


Miscellaneous Tool Set 


$04 


A 


QuickDraw II 


S05 


5 


Desk Manager 


$06 


6 


Event Manager 


$07 


7 


Scheduler 


$08 


8 


Sound Tool Set 


$09 


9 


Apple Desktop Bus Tool Set 


SQA 


10 


SANE 


SOB 


11 


Integer Math Tool Set 


$0C 


12 


Text Tool Set 


50E 


14 


Window Manager 


$0F 


15 


Menu Manager 


$10 


16 


Control Manager 


$11 


17 


System Loader 


$12 


18 


QuickDraw U Auxiliary 


$13 


19 


Print Manager 


$14 


20 


LineEdit Tool Set 


$15 


21 


Dialog Manager 


$16 


22 


Scrap Manager 


$17 


23 


Standard File Operations 


$19 


25 


Note Synthesizer 


$1A 


26 


NoLe Sequencer 


$1B 


27 


l-'ont Manager 


SIC 


28 


List Manager 
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□ Each routine within a too] set is assigned a permanent 
function number. Function numbers start at 1 in cacht_ 
and continue as successive integers. Certain standard alls 
be present in every tool set, and so certain function numba, 
are reserved Table 8-3 lists them. See the toolbox manual 
explanations of what each function must do. 

D There are some general rules and design consideration^ 
tool sets must follow. For example, tool sets receive conn 
full native mode; they must obtain any needed work space from 
the Memory Manager; they must provide some sort of interrupt 
environment; and they must restore the caller's operating 
environment before returning control to the caller, See the 
Apple IIGS Toolbox Reference for details on these and otb 
design requirements. 

Table 8-3 

Standard tool set routine numbers 



FuncNum Description 



1 Boot initialization 

2 Application startup 

3 Application shutdown 

4 Version information 

5 Reset 

6 Status 

Reserved for future use 

8 Reserved for future use 
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1 



This is as far as we can take you in this book. For your next steft 
spread out your development- environment manuals, Apple AGS 
technical manuals, and the Apple IIGS ToolBox Reference, and 
play with HodgePodge on the Apple IIGS or start your own 
applicaton. In parting, we'll give you a few hints — mostly 
summaries of the ideas presented throughout the book — and we! 
mention two organizations that can help you become a succesM 
Apple IIGS developer. 



Modify HodgePodge 

The easiest way to get started on your own desktop applicatiofltfc 
may be to take HodgePodge and modify it incrementally. 
Recompile it and run it after each small change to see how yofl 
changes look (or even if they work). 

You might begin by modifying text within dialog boxes, or 
changing the names of menu titles or items. As you become a 
little braver, try adding (or removing) menus or menu items, and 
adding (or removing) the subroutines called from those menu 
items. Remember that adding an Hem to a menu will require I 
changing the routine PoMenu as well as changing the menu 
definitions themselves — not to mention writing a subroutine that 
does something when the menu item is selected. 

Soon you'll become more ambitious, and you can branch in I 
almost any direction. Add a routine that plays a song when calla! 
Define a new window type, perhaps even one that permits the use 
to draw or type into it. Define a file type for that window type, in 
allow the user to save results to disk. Give HodgePodge the ability 
to cut and paste to and from the Clipboard, and display the ] 
Clipboard window. Play with menu- and window-frame colors 



Your imagination is your only real constraint. Have fun and 
challenge your limits; the Apple IIGS is a willing partner in ihis 
adventure. 
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Design your program carefully 

We've discussed design considerations for Apple IIGS desktop 
applications throughout the book, but some in particular are 
worth repeating. As you work on your own programs, either by 
modifying Hodgepodge or starting from scratch, keep these 
points in mind: 

■ Follow the Human interface Guidelines: Follow the underlying 
concepts, as well as the surface implementation, of the 
guidelines. They describe a tested and proven interface, 
familiar and friendly eo millions of users. If you go beyond the 
guidelines, make it a natural extension. 

■ Design data structures before writing code; Your menus, 
windows, controls, dialog boxes, and alerts influence program 
structure so strongly that they should be carefully planned and 
defined at the beginning. You'll save yourself wasteful rewriting 
and awkward paLching if your code organization flows naturally 
from the design of your data structures, 

■ Test for errors; Make it a habit to put error-testing code after 
toolbox calls. It can help inform the user and can keep your pro- 
gram from doing harmful things to the user's system or data. 

■ Save and restore: When a subroutine accesses the desktop, it 
may not always know the exact state of things. Note that many 
Hodge Podge routines start with a GetPort call to save the 
current state of the desktop, and end by restoring the desktop 
(with a SetPon call). It's another good habit to get into. 

■ Lock handles while In use: if your program has allocated a 
piece of memory accessed by a handle, be sure to lock it just 
before using it. A lot of memory errors are caused by trying to 
access data that has been moved. 

■ Unlock handles when not in use: Don't prevent the Memory 
Manager from doing its job. 

■ Dispose handles when finished: Don't prevent the Memory 
Manager from doing its job. 

■ Make It easy to translate: If you want to appeal to international 
markets, remember to place in one or more individual data 
areas all text that is to be displayed, so that it may be found 
and modified easily. 

■ Design for "Undo": Consider including a facility that allows the 
user to reverse his actions to undo a mistake. Your customers 
will be eternally grateful. 
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Join APDA 

If you are already a member of the Apple Programmers and 
Developer's Association (APDA), you know that it is the fastest 
way to get the most recent software, documentation, and otter 
information of interest to developers. If you are not a member, 
it s easy to join. 

APDA is a membership organization for both professional and 
advanced amateur programmers and developers. It was founded 
by Apple Computer and the A.P.P.L.E. Co-op near Seatde, 
Washington; its purpose is to publicize and distribute 
programming tools and technical documentation for Apple 
computers. 

APDA serves as a "one-stop shopping center." It offers both 
fimshed products from Apple and other vendors, and prerelease 
versions of many Apple development tools and documents. Some 
small-volume products, not suitable for the retail market are 
available only through APDA. Other products, scheduled forte 
retail market, are offered through APDA in prerelease versions, on 
an as-is (no support) basis. 

If you join APDA, you will receive quarterly catalogs (and more 
frequent updates) of the available material for both Apple II and 
Macintosh development. Membership is open to all interested 
parties. Yearly dues are 520.00. 

Write to 

Apple Programmer's and Developer's Association 
290 SW 43rd Street 
Eenton, WA 98055 

(206)251-6548 



Become an Apple Developer 

If you are a developer with a product soon to reach the 
commercial market, you may want to become an Apple Certified 
Developer. As a Certified Developer, you will receive monthly 
madmgs including a newsletter, Apple II and Macintosh Technical 
Notes, pertinent Developer Program information, and all the 
ktest news relating to Apple products. You will have access lorn 
Developer Hotline for general developer information 
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Once you are certified, Apple's Developer Technical Support staff 
can provide technical assistance during your product's evolution. 
Our Technical Support engineers will answer your development 
questions within 24 hours by electonic mail. 

The Certified Developer program is for professional hardware 
and software developers who plan to have a finished commercial 
product within 18 months. If you fit this description and are 
interested, please write for an application. You will need to submit 
information on previous products and your present business plan 
along with your completed application. 

Write to 

Developer Programs 

Apple Computer, Inc. 

20525 Mariani Avenue, M.S. 27W 

Cupertino, California 95014 

(408) 973-4897 



Licensing Apple software 

If the software you write uses all or part of some Apple software 
(such as ProDOS 16 or the Apple IIGS Toolbox), you will need to 
license the use of that software from Apple Computer. You 
needn't license any parts of HodgePodge you use, but you will 
need to license any system software that accompanies or is 
incorporated into your application, 

A modest yearly fee authorizes you to use Apple software in your 
product. There are no royalties. Please contact 

Software Licensing 

Apple Computer, Inc. 

20525 Mariani Avenue, M.S. 28B 

Cupertino, CA 95014 

Attn; Software Licensing Program 

(408) 973-4667 
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Appendix A 



Converting Macintosh I 
Programs to the Apple Mgs 



rf you have written a desktop application for the Macintosh, 
may be able to convert it to run on the Apple ires without 
completely rewriting it. On a conceptual level, the task should I 
rather simple— after all, program organization and toolbox 
capabilities are similar for both computers. But when it con 
implementation, there are many differences that require cai, 
attention to details of coding This appendix notes some of U 
details to keep in mind when converting Macintosh programs 
the Apple lies. 



High-level languages 



Programming in a high-level language can insulate you from 
many of the differences among machines. However, the 
individual toolbox calls are different enough between the 
Macintosh and Lhe Apple 1IGS that in most cases it will not be: , 
possible just 10 recompile Macintosh code and expect it to run or 
the Apple IIGS. 
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The best approach is probably to regard the conversion process 
algorithmically, rather than literally. In other words, don't expect 
that you will be able to drop a whole program or even any one 
routine, unchanged, into an Apple IIGS program. Use your 
Macintosh program's organization as a framework into which to 
place individually converted routines. Even though most of the 
organization and much of the original code can be translated 
exactly, you'll have to locate those statements, calls, and structures 
that arc incompatible with the Apple IIGS environment. 

This doesn't necessarily mean pouring over the source code line- 
by-line. In general, you might be able to port well-behaved high- 
level code, just by carefully locating and modifying tool calls and 
any code that accesses toolbox data structures. 

Of course, if you have a routine that makes no tool calls, accesses 
no tool structures, and otherwise makes no Macintosh -specific 
assumptions, you may indeed be able to convert it simply by 
recompiling it. 



Assembly language 

Approaching the conversion process algorithmically rather than 
literally is even more critical when converting programs written in 
assembly language. Besides toolbox differences, you are faced 
with fundamentally different microprocessor architectures and 
instruction sets, very different memory maps, and a host of other 
low-level differences between the two types of computer. The only 
possible aproach is to think of your Macintosh program as an 
organizational shell in which every routine will need extensive 
revision to convert correctly. 

Here are just a few of the differences to keep in mind. 

■ Registers: The 65816 does not have nearly the number of 
registers that the 680Q0 has, so you will have to store more of 
your variables in memory — usually local memory (direct page), 

■ Direct page: Direct page is an Apple IIGS concept that can be 
very useful, especially if you are constructing tables in memory 
and accessing them by offsets. If your Macintosh program 
allocates such data structures on the heap, you can gain 
efficiency by putting them onto the Apple IIGS direct page. 
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Stack; Your slack on the Apple IIGS is likely to be smaller^ 
what you are used to on the Macintosh, More of your v: 
and data structures will be allocated in other parts of memoi 

Memory space and. segmentation: Your program may have to 
run in less space on an Apple IIGS than it may be used to om 
Macintosh. Therefore, segmentation can be very important^ 
Break the program into segments, and use as many dynamm 
segments as possible. 

Video display: The Apple IIGS offers you two different Super 
Hi-Res graphics modes — 320 and 640 pixels across. Both ustfl 
color, but neither has square pixels. 



Toolbox differences 

If you compare the Macintosh and Apple IIGS toolboxes, youlli 
see that many routines have identical names and function in the 
same way. Many others do not, however, so watch out for 
differences when using the tools. In particular the required 
parameters and the order of the parameters may differ beP 
the Macintosh and Apple IIGS versions of a particular call. Be 
sure to look up each routine in the Apple IIGS Toolbox Re/a 
before using it. 

Some groups of tool calls are more alike than others, For 
example, many QuickDraw calls are identical or very similar j 
both environments. Thus, graphic routines might be relatively I 
simple to translate. On the other hand, calls that direcdy ace 
or manipulate memory, such as Memory Manager calls and 
handle manipulations, can operate very differently in the two 
environments — even when ihcy look the same. Be careful. 

Also keep in mind that the records that describe toolbox 
structures such as GrafPorts and controls are different. Fields 
exist in one environment may not be in the other. So be 
particularly careful if you access data structures direcdy. 

Some specific recommendations on how to handle toolbox 
differences follow. 
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Pascal HodgePodge Is listed In 

Appendix G. Furthermore, 
ndivldual routines are listed and 
described tbioughour the book. 
See Table 2-1, 



Resources 

To a Macintosh programmer, the term resource means something 
much more specific than a useful item. Resources are certain 
types of data structures, easily accessible by the programmer, that 
help to separate code from static data and make program 
modification simpler. 

The Apple IIGS has no predefined structures like resources, and no 
Resource Manager or resource editors For manipulating them. So, 
in conversion, you will have to move your resources from the 
resource fork of your file into your program code, either as 
separate data segments or files, or merged into the execution 
stream, The Pascal version of the sample program HodgePodge 
shows several ways to do this: 

■ Icons: You can define your icons by directly creating a pattern 
in memory, as Hodgepodge does with the Apple icon in 
InitGlobala (file HP. PAS). 

■ Text strings: Instead of a string or string list resource, you can 
define your strings in initialization routines (as HodgePodge 
does with its menu strings), or in the individual routines in 
which they arc needed (as HodgePodge does with prompt 
strings in the Standard File dialog boxes). 

Remember, keeping all your strings easily accessible will make 
the program more convenient to translate or otherwise modify. 

■ Window and dialog box templates: The templates (DLOG, 
WIND, ALRT, and DITL resources on the Macintosh) used to 
define your windows and dialog boxes, and the controls and 
items within them, must be defined within the body of your 
Apple IIGS code. 

Each time it opens a window, HodgePodge defines and 
initialises a parameter list that controls the window's 
appearance (part of the routine DoTheOpen in window. pas). 
When it creates an alert box, it calls a routine 
(MakeATemplate in DIALOG, P AS) that defines the 
characteristics of an alert box and two items within iL 

Other resources in your Macintosh program will need to be 
converted similarly. 
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TaskMasfer or GetNextEvent? 

The Apple IIGS offers at least one very useful event-handling 
capability not yet available on the Macintosh: Taskmaster. 
TaskMaster automatically handles many standard events for 
standard types of windows— resizing, dragging, scrolling, updating 
and activating, and so on. 

On the other hand, the Apple IIGS also supports "normal" event* 
handling with GetNextEvent, just as on the Macintosh. So it migk 
seem more efficient to keep that same GetNextEvent organization 
when converting an existing Macintosh program. 

Usually it is not. Unless your program constructs unconventional 
windows or handles them in an unusual manner, it is probably 
best to change from GetNextEvent to TaskMaster when making the 
conversion. Using TaskMaster may allow you to eliminate entire 
routines from your progam, routines that would otherwise need 
individual attention to convert correctly. 

HodgePodge, for example, has no update routine, no activate 
routine, no scrolling procedure, no window-dragging or -resizing 
routines, and yet it supports windows that do all those things. It 
may greatly simplify your conversion to switch to Taskmaster 



QuickDraw II 

QuickDraw II on the Apple HGS is quite similar to QuickDraw on 
the Macintosh, apart from extensions to support Apple IIGS color 
display. However, keep the following in mind: 

□ The conceptual drawing space for QuickDraw n has boundary 
coordinates -lfSK, -l6K, 16K, 16k, compared to -32K.-32K and 
32K,32K on the Macintosh. 

□ QuickDraw ir s pixel images arc similar to Macintosh 
QuickDraw's bit images, but pixels are described by more than 
one bit each. Bit images such as icons will have to be 
converted to pixel images, with either two or four bits per pixel 
Icons are not as restricted on the Apple IIGS as they are on the 
Macintosh. Besides having color, they may be of arbitrary 
height and width, rather than 32 pixels (bits) on a side. 
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You won't need to change most drawing commands — your 
black-and-white Macintosh drawings will convert directly to 
white- an d-black drawings on the Apple IIGS screen. 

There will be some change in aspect ratio of images and drawn 
objects in transferring to the Apple IIGS screen, and significant 
changes in overall size — Super Hi-Res pixels are not square and 
are significantly larger than Macintosh screen pixels. 

Text drawing and text measurement on the Apple IIGS are 
similar to their treatment on the Macintosh. The Apple IIGS 
font definition is similar to that of the Macintosh, and a simple 
conversion algorithm allows the IIGS to use any font developed 
for the Macintosh. Most Macintosh QuickDraw text calls are 
duplicated precisely in QuickDraw II. 

Some calls have been added to handle the est ring data type 
(a sequence of characters terminated by a byte). 

QuickDraw II does not scale text — the Font Manager does. In 
general, the interaction between the Apple IIGS Font Manager 
and QuickDraw II is different from the close relationship 
between the Font Manager and QuickDraw on the Macintosh. 
Font selection on the Apple IIGS requires a little more care 
than on the Macintosh. 



File system differences 

ProDOS l6 is the Apple IIGS operating system for desktop 
applications. There are ProDOS 16 calls equivalent to most 
Macintosh File Manager calls, but some parameters are different 
or are used differently. If your Macintosh application makes File 
Manager calls, they will have to be translated to ProDOS 16 calls. 

On the other hand, if your program is written in a high-level 
language and uses only that language's file access facilities, you 
might not have to do any translating at all. On recompiling under 
a IIGS development environment, your file calls will be translated 

As noted under "Resources 1 ' earlier in this appendix, files do not 
have separate resource and data forks. Data stored as resources in 
your Macintosh files will have to be redefined and stored as 
standard ProDOS l6 files. 
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If your program handles all its file access through Standard File 
Operations, it will not have to manipulate pathnames explicitly, 
just as on the Macintosh, the Standard File Operations Tool Set 
on the Apple IIGS takes care of all that. But if you do access files 
by name, please note these differences from the Macintosh file 
system: 

□ Filenames under ProDOS 16 are more restricted than on the 
Macintosh, Only the characters A-Z, 1-9, and the period (.) at< 
permitted, and the maximum length is 15 characters. 

□ ProDOS 16 permits you to define up to 9 prefixes, for 
convenient simultaneous access to files in several different 
subdirectories. 

ProDOS 16 uses a hierarchical file system, in which files are 
grouped into subdirectories and accessed by pathname. The 
present Macintosh file system is also hierarchical, but if you 
have an early Macintosh program written for the flat file 
system, you may have to modify it to account for pathnames 
instead of just filenames. 



Other toolbox differences 

As you get involved in the conversion process, you will of course 
discover many oilier differences, some subtle and some obvious, 
between the Macintosh and Apple IIGS toolboxes. There are far 
too many to list in this appendix, but here is a sample; 

■ Memory Manager: The Apple IIGS Memory Manager is 
conceptually very similar to ihe Macintosh Memory Manager. 
However, because of the 65C816 microprocessor and the 
architecture of the Apple IIGS, the Apple IIGS Memory 
Manager's calls are very different, and its internal data 
structures totally different, from those of the Macintosh. Pay 
extra-close attention to converting Memory Manager calls and 
manipulating its data structures such as pointers and handles. 

■ Window Manager/Control Manager: Windows and controls i 
be handled differently in several ways, largely because of the 
Window Manager routine TaskMaster. The Apple IIGS has 
window types that include scroll bars (frame scroll bars) 
manipulated automatically by TaskMaster. The use of frame 
scroll bars greatly simplifies window handling. 
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Frame scroll bars: If you use TaskMaster and have it manipulate 
frame scroll bars, remember that the scroll bars are pan of the 
window frame, not the content region. That is, unlike standard 
scroll bars on a Macintosh window, they are outside the 
window's port rectangle. That may affect your clipping and 
drawing commands. 

Desk Accessories: If you are converting a Macintosh desk 
accessory, it will become a new desk accessary on the Apple 
IIGS. 

Standard File Operations: The Disk buiLon on the Apple IIGS 
works differently from the Drive button on the Macintosh. 
When a user clicks the Disk button, Standard File first looks at 
the disk in the same drive the current disk is in. If the current 
disk is no longer in that drive, the disk in that drive becomes 
the current disk. If the current disk is still there, the Disk button 
moves to the next disk in the ProDOS chain. The Disk button 
works this way because a user can change disks without the 
system's knowledge. 

Printing: On the Apple IIGS, the Choose Printer function is 
part of the Print Manager, rather than part of the Chooser desk 
accessory as on the Macintosh. To support printing, you will 
need to add a Choose Printer menu item to the File menu, and 
create a short routine to handle it. 
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Appendix B 



Enhancing Standard 
Apple II Programs 



If you have written a ProDOS 8-based program for a standard 
Apple II computer (64K Apple II Plus, Apple He, or Apple He), yen 
should be able La run it without modification on the Apple IIGS. 
The only noticeable difference will be its faster execution because 
of the greater clock speed of the Apple IIGS — and even that 
difference can be eliminated if you wish. However, the program 
will not be able to take advantage of any advanced Apple IIGS 
features such as Its large memory, the toolbox, the mouse-based 
interface, and the new graphics and sound abilities. 

This appendix discusses some of the basic alterations you can 
make to upgrade a ProDOS 8 application for various execution 
modes on the Apple IIGS. Depending on the program's size and 
structure and the new features you wish to install, those changes 
may range from minor to drastic. 

♦ High-level languages- This discussion is primarily about 
assembly-language programs. If you have a standard Apple n 
program written in a compiled BASIC or other high-level 
language, converting it to run in native mode on the Apple IIGS 
may require nothing more than recompiling it on an 
equivalent Apple IIGS development system. Accessing the 
toolbox may then be as easy as adding the calls to your 
original source code. 
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S5B16 assembly language is 
described In the Apple ItGS 
Programmer's Workshop 
Assembler Reference. 



Re:ocotable code and the 
Memory Manager are discussed 
h Chapter 6. 



Conceptual differences 

For ihe purpose of program conversion, there are perhaps three 
main areas of difference between traditional Apple II computers 
and the Apple IICS: 

■ Hardware execution modes; The 65C816 microprocessor 
executes in both native mode and 6502 emulation mode. In 
fact, there are at least three modes to consider: 

□ Emulation mode (e flag, m flag, and x flag set). The 
processor functions like a 6502. 

D Native mode with the m flag and x flag set. The processor 
has all 65C816 features, but the accumulator and index 
registers remain 8 bits wide. 

p Full native mode (e flag, m flag, and x flag cleared). All 
65C816 features are available, and the accumulator and 
index registers arc 1 6 bits wide. 

The 65816 microprocessor adds several new addressing modes 
and instructions to those of the 6502. All 6502 and 65C02 
instructions are still available, but the new larger registers and 
relocatable stack and direct page add flexibility and power to 
the system. 

■ Tool sets-. The toolbox is the essence of what makes the Apple 
IIGS more powerful and convenient than other Apple II 
computers. To write the kinds of programs described in this 
book, you need access to the toolbox. Tool calls can be made 
while in full native mode only. 

The Apple ITGS also provides a sophisticated loader and a 
software memory manager. To take Full advantage of the 
system, you should write relocatable code, and request any 
memory you need through Memory Manager calls. Otherwise 
your program will be incompatible with other programs in 
memory, such as desk accessories and memory-resident 
utilities. 

■ Operating systems: The Apple IIGS comes equipped with two 
operating systems; ProDOS 8 and ProDOS 16. Unaltered 
standard-Apple II applications can run on the Apple IIGS only 
under ProDOS 8. They cannot access tool sets or ProDOS 16. 
They can make ProDOS 8 calls only while in emulation mode. 
The ProDOS 8 global page is supported, but again only in 
emulation mode. 
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ProDOS 8 te cfiscussgd in the 
ProDOS 8 Technical Reference 

Manual. 
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See "Setting Up Direct- 
Page/Stack Space", In 
Chapter 6. 



Writing a hybrid application is not easy, and the results for 
toolbox access are not always entirely satisfactory. You'll need to 
address at least these issues: 

■ Loading RAM patches: If your program is self-booting (starts up 
directly under ProDOS 8) on the Apple TIGS, ProDOS 16 and 
the System Loader will not have been activated. Therefore RAM 
tool sets and RAM patches to the ROM tool sets will not be in 
place. There are several possible responses to this problem: 

□ Do without the patches or RAM-based tools. 

□ Write your own RAM-based tool set, convert it to ProDOS 8 
binary format, and load and install it yourself. See "Writing 
Your Own Tool Set," in the Apple HGS Toolbox Reference. 

a Allow your program to be launched only from a ProDOS 16- 
based finder or launcher, after the normal ProDOS 16 boot 
sequence has loaded all the RAM patches and RAM tool sets. 

■ Switching stacks and zero pages: You have a standard stack 
and zero-page available in emulation mode, but you also need 
a direct-page/stack space for use by tool sets in native mode. 
Set it up as needed. When switching from emulation mode to 
native mode and back, you must save the current value of the 
stack pointer, and set the stack pointer to the proper value for 
the mode you are about to enter. Likewise, the direct register is 
set to zero upon entering emulation mode; you must save its 
value before switching to emulation and restore it upon 
returning 

For detailed instructions on saving and restoring the proper 
environment while switching execution modes, see "Notes for 
Programmers" in the Apple ItCS Firmware Reference. 

u Staying In bank $00 or disabling Interrupts: Any code that your 
program calls while in emulation mode must be in bank $00, or 
else interrupts must be disabled. The Program Bank register is 
not saved or restored when an interrupt occurs in emulation 

mode. 
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The FWEnrry call Is part of the 
Miscellaneous Tool Set See the 
Apple iigs Toolbox Reference 



Insert parts of your 6502 code 

Because the 65C816 processor recognizes the 6502 instruction* 
it may be possible to use significant sections of your code, 
unchanged or only slightly modified, in a native-mode, ProE 
16-based application. That is, instead of making a hybrid 
application, you might write a new Apple IIGS application, but 
save time by incorporating as much of your older, 6502-based 
code as possible. In most cases this option is far better than 
writing a hybrid application; it puts ProDOS 16 and the tool j 
much more directly at your program's disposal. 

How successful you can be depends greatly on the specific 
content of your existing code. Koutines that draw to the screen 
otherwise duplicate the tasks performed by tool sets may not 
worth convening to native-mode execution, Code that uses 
absolute address references or that must itself occupy specific 
addresses will be incompatible with native-mode memory 
management. Instructions that can't reach everywhere in the 
16-megabyte Apple IIGS memory space (such as JSR rather than 
JSL) can cause a lot of problems, depending on where your codj 
and data are and what system features you need to access. 

In spite of these and other problems, it may be possible to use 
large portions of certain types of 6502-based code, relatively 
unchanged, in native-mode Apple lies applications. Here are jJ 
a few considerations. 

■ Register width: In most cases your 6502 code will require shol 
(8-bit) accumulator and index registers when running in native 
mode. That is, the m- and x-bits need to be set ( =1) when 
e-bit is cleared ( -0). However, see the next note. 

■ Stack manipulation: The stack pointer value is commonly 
and restored with the instruction pair TSX. , TXS. If perform^ 
in 8-bit mode, this sequence destroys the high-order byte of (lie 
stack pointer. To be safe, do ail slack manipulation with JcT-ttf 
registers. 

■ Firmware entry points: Replace all calls to specific firmware I 
entry points with FWEntry tool calls. FWEntry allows you while 
m native mode, to make calls to (6502) code that executes in 
emulation mode; it saves and restores the Data Bank and 
Direct registers. 



native 

n the 

Drmed 
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Data and buffer allocation: Remove absolute addresses that 
define your data buffers or other entry points. For example, if 
your program reserves a 4K buffer space with an equate such as 
BUFFER EQU $8 000, replace that with something such as 
BUFFER DS $1000, which reserves a $1000-byte buffer but 
doesn't require it to start at address $8000, 

Input/output: I/O in a standard Apple II computer takes place 
by accessing locations in the $Cxxx address space Q/O 
memory). In the Apple 1IGS, I/O memory exists only in banks 
$00, S01, $E0, and $E1. Therefore, if your code is running 
anywhere in expansion RAM, it cannot perform I/O unless data 
accesses to $Cxxx are made in long addressing mode, to access 
the proper bank. 

However, the timing of much I/O is critical and, because a 
long-addressing load instruction takes an extra cycle to execute, 
you may not be able to change the addressing mode. 

One way around this is to set the data bank register to $00 
before executing the I/O instructions. Then, however, any other 
data in the same bank as your code becomes inaccessible — but 
that may not be a problem in your particular case. 

There are many other alternatives, including creative use of the 
direct page and isolating timing -critical code, that can be useful 
in various individual situations. Every situation is unique — feel 
free to be creative. 



Rewrite if to run under ProDOS 16 

Modifying your entire program for full 16-bit native mode 
operation on the Apple IICS is a more ambitious task, but it may 
well be worth it for the greater number of features you can access. 
In order to run entirely in native mode, under ProDOS 16 and 
with the tool sets always available, your program needs to 
consider at least the following points. 

■ Managing memory: Because the Apple IIGS supports 
segmented load files, one of the first decisions to make is 
whether and how to segment the program (both the original 
program and any added pans). First, make your code 
relocatable so the Memory Manager can control where it is 
loaded. You'll need to specify memory-block attributes in 
addition to modifying your code as described in the previous 
section, "insert Pans of Your 6502 Code." 
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Refer to the detailed descriptions 
In Chapters 9 through 1 3 of the 
Apple IIgs ProDOS 1 6 J?e feren ce to 
see which ProDOS 16 colls pre 
different from their ProDOS 8 
counterparts, 



See "Setting Up Dlrect- 
Poge/Stock Space." In 

Chapter 6. 



Object module format is 
documented In the Apple ttss 
Programmer's Workshop 

Reference; 



APW is discussed in Chapter 7. 



Memory management under native^mode operation on trJ 
Apple IIGS is completely different from standard-Apple III 
methods. If your program allocates its own memory space ini 
marks it off in the ProDOS 8 global page bit map, the 
enhanced version must be altered so that it requests all neede 
space from the Memory Manager. 

I Converting operating-system calls: For most ProDOS 8 dm 
there is an equivalent ProDOS 16 call with the same nanuS 
each call block must be modified for ProDOS 16, and ead| 
parameter block must be reconstructed in the ProDOS 16 
format. 

For other ProDOS 8 calls, a ProDOS 16 near-equivalent 
performs a slightly different task, and the original code 
have to be changed to account for that. 

Yet other ProDOS 8 calls have no equivalent in ProDOS l| 
your program uses any of these calls, they will have to be 
replaced as appropriate, 

i Removing global page references: Any access your origin. 
program makes to the ProDOS 8 global page must be repll 
by appropriate ProDOS 16 or toolbox calls. 

i Converting stack and zero page; Under ProDOS l6 in 
native mode, you are not constrained to the fixed stack and 
zero-page locations provided by ProDOS 8 in emulation i 
You may either let ProDOS 16 assign you a default IK u 
page/stack space, or you may define a direct-page/stack 
segment in your object code. In either case, the loader i 
place the segment anywhere in bank $00 — you cannot i 
any specific address to be within the space. 

Assembling: Once your source code has been modified i 
augmented as desired, you need to reassemble it. You mustj 
an assembler (or compiler, for high-level languages) that 
produces object files in Apple IIGS object module format 
(OMF); otherwise the program cannot be properly linked i 
loaded for execution. Using a different assembler may me 
that, in addition to modifying your program code, you'll L 
to change some directives to follow the syntax of the new 
assembler. 

If you have been using the EDASM assembler, you will not I 
able to use it to write Apple IIGS programs. Instead, you _ 
the Apple IIGS Programmer's Workshop (APW). APW is a s{ 
development programs that allow you to produce and edit 
source files, assemble/compile object files, and link them 
proper OMP load files. 
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After your revised program is linked, assign it the proper Apple 
IIGS application file type (normally $B3) with the APW 
FileType command. 



Start from scratch 

In the long run, this is the best alternative in most cases. Combing 
Lhrough your code line-by-line to make all the conversions 
described in the previous sections — even if it works — will 
probably yield a product that's only half successful. Why not start 
fresh, maintaining your original design and concepts but writing 
new code that truly takes advantage of the power and convenience 
of the Apple IIGS? 

The purpose of this book has been to show you that it is both easy 
and rewarding to write desktop applications for the Apple IIGS. It 
has also shown you that such applications have a structure, an 
approach to the hardware, and a user interface that are 
fundamentally different from those of traditional Apple II 
software. Don't confine yourself unnecessarily; a clean slate is the 
best way to start. Take advantage of the freedom the Apple IIGS 
gives you! 
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Files on an Apple Mgs 
System Disk 



A system disk is a 3.5-inch disk, 5.25-inch disk, or hard disk that 
has the files necessary for an Apple IIGS to start up when turned 
on or rebooted, It also has any files needed to support the 
specific application programs on the disk. This appendix shorn 
you what files a system disk must have. 

Because not all applications have the same needs, not all systi 
disks are alike. In particular, there are complete system disks and 
application system disks. 



Complete system disk 

Every Apple IIGS user (and programmer) needs at least one 
complete system disk, It is a pool of system software resources, 
and may contain files missing from some application system 
disks. Table C-l lists the contents of a complete system disk. 

♦ Note: The word complete doesn't mean that the system disk :. 
all the files that may be on your system disk — only that it has 
all the available system resources. For example, most system 
disks include files containing disk utility programs or finder- 
style program launchers. Those programs aren't considered 
here. 
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Table C-l 

stents of a complete system 




disk 



Dfwclory/Flle 



Description 



A routine that loads the proper operating system and selects an 
application, both at boot time and whenever an application quits. 

A subdirectory containing the following hies: 

The ProDOS 8 operating system. 

The ProDOS 16 operating system and Apple 11GS System Loader. 

The first program executed: typically a program launcher or finder. 

A subdirectory containing the standard system libraries. 

A subdirectory containing all RAM-based tool sets. 

A subdirectory containing all fonts. 

A subdirectory containing all desk accessories. 

A subdirectory containing printer and port drivers. 

A subdirectory containing system initialization programs. 

A permanent initialization file containing patches to ROM and a 
program Eo install them. This is the only required file in the 
SYSTEM. SETUP/ subdirectory; it is executed before any others that 
may be in the subdirectory. 

A permanent initialization file that initializes the AppleTalk network. 

Another file for AppleTalk inti a ligation. 

The Applesoft BASIC system interface program. 

A subdirectory containing files supporting the built-in Appletalk 
network interface. 

The complete system disk is an 800K byte, double-sided 3. 5-inch 
disk; the required files will not fit on a 140K, single-sided 5.25-inch 
disk. However, sec "Application System Disks" (next). 

When you boot a complete system disk, it executes the file 
SYSTEM /START. 



ATINIT 
ATLOAD . 

BASIC. SYSTEM 
APPLETALK/ 



Complete system disk 
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The SYSTEM. SETUP/ subdirectory 

The SYSTEM. SETUP/ subdirectory may contain several dif_ 
types of files, all of which are loaded at boot time. They iricB 
the following. 

■ TOOLSETUP; This file must always be present; it is execufl 
before any others in SYSTEM. SETUP/. TOOL, SETUP insfl 
and initializes any RAM patches to ROM-based tool setsj 
TOOL . SETUP is finished, ProDOS 16 loads and executes the 
remaining files in the SYSTEM, SETUP/ subdirectory, which 
may belong 10 any of the categories listed below. 

■ Permanent initialization ales (filetype $B6> These files ait 
loaded and executed just like standard applications (ivpc $BJ), 
but they are not shut down when finished. They also must hivt' 
certain characteristics: 

□ They must be loaded in nonspecial memory. 

d They cannot permanently allocate any stack/direct-pa M 
space. 

□ They must terminate with an RTL (Return from subrourjB 
Long) rather than a QUIT. 

■ Temporary Initialization files (type $B7> These files arelfl 
and executed just like standard applications (type $B3), zM 
ihey are shut down when finished. They must terminate w® 
RTL rather than a QUIT. 

Although they are loaded and installed in the system at the fl 
time as the files in SYSTEM . SETUP/, desk accessories actua 

reside in the subdirectory DESK . ACCS/. There are two tyj 

■ New desk accessories (type $BS): These files are loaded bj 
executed. They are put in nonspecial memory. 

■ Classic desk accessories (type $B9> These files are loaded 
not executed. They arc put in nonspecial memory. 



Application system disks 

Each application program or group of related programs cool 
on its own application system disk. The disk has all of the sya| 
files needed to run that application, but it may not have all tl 
files present on a complete system disk. Different application 
may have different system files on their application system i 
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Table C-2 shows which files must be present on all application 
system disks, and which files are needed only for particular 
applications. In some very restricted instances, it may be possible 
to fit an application and its required system files onto a single- 
sided (14QK) 5.25-inch disk; most applications, however, require at 
least one double-sided (800K) 3.5-inch disk. 



Table C-2 

Required contents of an application system disk 



Directory /File 



Required? 



PRODOS 
SYSTEM/ 

P8 

P16 

START 

LIBS/ 

TOOLS/ 

FONTS/ 

DRIVERS 

DESK.ACCS/ 
SYSTEM, SETUP/ 

TOOL, SETUP 

BASIC, SYSTEM 
APPLETALK 

Important 



Yes 

Yes 

(Required if the application runs under ProDOS 8) 

Yes 

(Required if a START file, such as a finder, is to be used) 

(Required if system library routines are needed) 

(Required if the application needs RAM-based tools) 

(Required if the application needs fonts) 

(Required if the application does any printing or serial 
communication) 

(Required if desk accessories are to be provided) 

Yes 

Yes 

(Required if the application is written in Applesoft BASIC) 

(Required if the application supports printing to a LaserWriter or 
otherwise uses AppleTalk) 

Tha files PRODOS. PB r and PI 6 all have version numbers. Whenever 
It loads an operating system (at startup or when launching an 
application), PRODOS checks the P8 or PI 6 version number against 
its own. If the numbers do not match, It Is a fatal error. Be careful not 
to construct an application system disk using incompatible versions 
of PRODOS, P8, and PI 6. 



Application system disks 
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Appendix D 



HodgePodge Organization 



This appendix presents three topics related to the organize 
the sample program HodgePodge. 

n It lists all HodgePodge routines and their source Tiles for all 
three languages. 

□ It diagrams the routines that execute when HodgePodge opens 
a window. ° ' 

□ It discusses and lists Hodgepodge's error-handling proced 



HodgePodge subroufines 

Tabic D.] lists all HodgePodge routines. Column 1 lists in 
alphabetical order, each routine in the Pascal version. Column 
shows what source file each Pascal routine is in. Columns 3 ar 
name the source files containing the equivalent C and 65816 
assembly-language routines. Column 5 gives the number of the 
chapter m wh.ch the Pascal version of each routine is discus 
and hated. Column 6 briefly notes what each routine does 
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Table D-l 

HodgePodge routines (complete) 



Routine 


Pascal file 


Cfl* 


Assembly file 


Listed In... 


Function 


AddToMenu 


MENU. PAS 


MENU.CC 


MENU. ASM 


Chap, 5 


adds an item 


AdjWind 


WINDOW. PAS 


WINDOW.CC 


WINDOW. ASM 


Chap. 5 


deletes an item 


AskOser 


PAINT. PAS 


WINDOW. CC 


WINDOW. ASM 


Chap. 5 


which file to open 


CheckDiskError 


DIALOG. PAS 


DIALOG.CC 


DIALOG, ASM 


App. D 


error alert box 


CheekFrontW 


EVENT. PAS 


EVENT. CC 


EVENT . ASM 


App, G 


adjusts menu items 


Check ToolErr or 


DIALOG . PAS 


DIALOG.CC* 


DIALOG. ASM 


App. D 


system failure 


DisableAll 


EVENT. PAS 


EVENT. CC 


EVENT. ASM* 


App.G 


adjusts menu items 


Disableltems 


EVENT. PAS 


EVENT . CC 


EVENT. ASM* 


App.G 


adjusts menu items 


Di spF o n tWi ndow 


FONT . PAS 


FONT.CC 


FONT. ASM 


Chap. 2 


calls text-draw 


DoftbQUtltem 


DIALOG. PAS 


DIALOG.CC 


DIALOG. ASM 


Chap. 4 


"About" box 


DoChooaeFont 


FONT. PAS 


FONT.CC 


FONT. ASH 


Chap. 3 


user selects font 


DoChooserltejn 


PRINT. PAS 


PRINT. CC 


PRINT. ASM 


Chap- 5 


selects printer 


DoCloseltem 


WINDOW. PAS 


WINDOW.CC* 


WINDOW. ASM 


Chap. 2 


doses a window 


DoMenu 


MEND. PAS 


MENU . CC 


MEN", ASM 


Chap. 2 


dispatches menus 


DoOpenltetn 


MENU. PAS 


WINDOW.CC 


WINDOW. ASM 


Chap. 4 


to open a window 


DoPrintlteni 


PRINT. PAS 


PRINT. CC 


PR INT. ASM 


Chap. 5 


calls printing 


D&Quitltem 


MENU" .PAS 


EVENT . CC 


EVENT . ASM 


App.G 


sets quit variable 


Do-Save It em 


PAINT. PAS 


WINDOW.CC 


WINDOW. ASM 


Chap. 5 


to save a file 


DoSetMono 


FONT . PAS 


FONT.CC 


FONT. ASM 


App. G 


toggles menu item 


DoSetUpItem 


PRINT, PAS 


PRINT. CC 


PRINT. ASM 


Chap, 5 


user page -setup 


DoTheOpen 


WINDOW. PAS 


WINDOW.CC 


WINDOW. ASM 


Chap. 4 


Opens a window 


DoWindow 


MEND . PAS 


WINDOW . CC 


WINDOW. ASM 


App. D 


brings window to from 


DrawTopHindow 


PRINT. PAS 


PRINT. CC 


PRINT. ASK 


Chap. 5 


printing routine 


Enable I terns 


EVENT, PAS 


EVENT . CC* 


EVENT. ASM* 


App. G 


adjusts menu items 


FindMaxWidth 


■ ■ 


WINDOW.CC 


WINDOW. ASM 


App- E. F 


sizes font window 


BideA 11 Windows 


WINDOW. PAS 


WINDOW.CC 


WINDOW. ASM 


App. G 


closes windows 


HideP lease Wait 


DIALOG. PAS 


DIALOG.CC 


DIALOG, ASM 


Chap. 4 


hides "wait" dialog 


HodgePodge 


HP. PAS 


HP.CC* 


HP. ASM 


Chap. 2 


main program 


InitGlobals 


GLOBALS . PAS 


HP.H* 


GLOBALS. ASM* 


Chap. 2 


initializes variables 


LoadOne 


PAINT. PAS 


EVENT. CC 


10. ASM 


Chap. 6 


reads a picture file 


Ma in Event 


EVENT. PAS 


EVENT. CC* 


EVENT. ASM 


Chap. 2 


main event loop 






Hodgepodge subroutines 
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Table D-l (continued) 

Hodge Podge routines (complete) 



Routine 


Pascal file 


CBfe 


Assembly file 


Listed In... 


Funclfo 


MaXeATemplate 


DIALOG, PAS 


DIALOG.CC* 


DIALOG. ASM* 


Chap. <i 


creates alert rtea 


ManyWindDialog 


DIALOG , PAS 


DIALOG ,CC 


DIALOG. ASM 


App. G 


caution ale 


MountBootDIsk 


DIALOG. PAS 


DIALOG.CC 


DIALOG. ASK 


App. D 


asks user for dis 


OpenPilter 


PAINT. PAS 


WINDOW. CC 


WINDOW. ASM 


Chap. 6 


alters file displi 


OpenWindow 


WINDOW , PAS 


WINDOW, CC 


WINDOW, ASM* 


Chap. 4 


to open a windm 


Paint 


PATNT.PA5 


WINDOW. CO 


WINDOW. ASM 


Ctiap, 2 


calls picture-cYjl 


Pairttit 


PAIKT.PA5 


WINDOW . CC 


WINDOW. ASM 


Chap. 3 


draws pictun 


SaveOne 


PAINT. PAS 


EVEKT.CC 


10. ASH 


Chap. 6 


saves a picture fl 


SetUpDefault 


PRINT. PAS 


PRINT. CC 


PRINT. ASM 


Chap, 2 


makes print recon 


SetUpForAppH 


EVENT. PAS 


EVENT. CC 


EVENT. ASM 


App. G 


adjusts menu item 


SetOpForDAH 


EVENT. PAS 


EVENT. CC 


EVENT. ASM 


App. G 


adjusts menu {teat 


SetUpMenus 


MENU, PAS 


MEHU.CC 


MENU. ASM 


Chap, 2 


makes menu la 


SetUpWindows 


WINDOW, PAS 


WINDOW. CC* 


GL0BAL5.ASM* 


Chap. 2 


sets size & loe 


ShovFont 


FONT. PAS 


FONT.CC 


FONT. ASM 


Chap, 3 


draws ion 


ShcwPleaseWait 


DIALOG. PAS 


DIALOG, CC 


DIALOG. ASM 


Chap.4 


does "wait" dialog 


ShutDownToola 


HP. PAS 


HP.CC 


INIT.ASM 


Chap. 2 


shuts dowr 


StartUpTools 


HP. PAS 


HP.CC 


IN IT, ASM 


Chap 2 


starts ail tool; 


* Name or content of 


routine is slightly different from the Pascal version. 







* * Docs not exist in the Pascal version. 



Execution sequence: opening a window! 

When a window is opened in HodgcPodge, several routines are 
called in sequence, starting with DoOpenltem. The execution 
sequence starts out in the same way whether the window to be 
opened is a font window or a picture window. 

The routines involved with opening a window are described in 
several different chapters in this book, To help you follow the 
sequence, we diagram the sequence of subroutine calls here, for 
both font windows and picLure windows. 



304 



Appendix D: Hodgepodge Organization 



Opening a font window 

A font window is opened when the user chooses Display Font 
from the Fonts menu. That causes execution to pass to the routine 

DoOpenltem, which calls OpenWindow. OpenWindow first calls 
DoChooseFonl, then DoTheOpen to actually open the window. 

After Openwindow is finished, DoOpenltem calls AddToMenu, 
and [hen execution passes back to the main event loop, See 
Figure D-l. 

«> Note: The dimmed boxes in Figure D-l represent routines 
called to open a picture window (Figure D-2). 



OpenWindow ~ 



DoOpMltam 



AddloMww 



DoChoo»Fonl 



0oTh»Op»n 



Figure D-l 

Execution sequence: opening a font window 



Opening a picture window 

A picture window is opened when the user selects Open from the 
File menu. Just as when a font window is opened, execution passes 
to the routine DoOpenltem, and to OpenWindow. 

In this case Openwindow calls AskUser, AskUser first calls 
SFGetFile — part of the Apple Hgs Toolbox, not HodgePodge. 
SFGeiFilc calls the HodgcPodge routine OpenFilter while it is 
displaying filenames, Once a filename is chosen, AskUser calls 
LoadOne to open the file. OpenWindow then calls DoTheOpen to 
actually open the window. 



Execution sequence: opening a window 
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DoOponltem 



After Open Window is finished, DoOpenltem calls AddToMend 
and then execution passes back to the main event loop. See Figure 
D-2. 

♦ Note: The dimmed boxes in Figure D-2 represent routines 
called to open a font window (Figure D-l). 






r 



OpenWindow 



AddToMsnu 



- DoChoosefon) 



SFGetFlle — opanRHw 



L 



DoTheOpen 



LoodOne 



Figure D-2 

Execution sequence: opening a picture window 



Error handling 

HodgePodge has three routines that handle error conditions: 
CheckToolError, MountBootDisk, andCheckDiskError. 
This section lists them and discusses what they do, 



CheckToolError 

CheckToolError is called only when the program is starting up, 
It is a very simple error handler, because any error it detects is 
made fatal, and because it puts up no message box for the usee. In 
general, CheckToolError cannot put up a dialog box becauseH 
the Dialog Manager may not have been started when 
CheckToolError is called. 
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Appendix D: HodgePodge Organization 



teckTooiError Is In the source file 
LOG.PAS. 



CheckToolError is called after each tool startup call. It checks 
the value of the global variable toolErrorNum; if the number is 
nonzero an error has occurred. In that case CheckToolError 
calls the System Failure Manager, which puts up the "sliding 
apple™ error screen and halts execution, 

•t* Input; CheckToolError has a single input parameter: an 
integer location number that specifies what part of the 
program made the call, Each call to CheckToolError passes 
a different integer. The integers have no significance or 
purpose other than helping the programmer locate the part of 
the source code that generated the error. 



:ocedure CheekToolSrror {Where: Integer) 

toolErrorSave: Integer; 
deathMsg : String; 



fcegin 
toolErrorSave := ToolErrorNum; 
deathMsg : = 

■ At SXXXX; Could not handle error $'; 



if taolEirorSave <> then 
begin 
Int2gex (Where, StringPtr{Longint 

{^deathMsg) +6) , 4] ; 
SyaFailKgr CtoolErrorSave, deathMsg) ; 
end; 
end; 



{begin CheckToolError...) 



(string to display] 



{save the error number) 

{This is the message with-,} 
;...a dummy location number) 

{If there HAS beer, an error.,.) 

{...convert loc, no. to a string... J 
{...and insert it in message) 
{Then go to system failure) 
{end of IF error nonzero) 
(End of CheckToolError} 



MountBootDisk Is in the source fie 
DIALOG.PAS. 



MountBootDisk 

MountBootDisk is called during the loading of RAM-based tool 
sets, if the disk containing the tool sets is not already on line. 
MountBootDisk makes use of the Tool Locator routine 
TLMount Volume, which displays a dialog box prompting the user 
to remount the boot volume. See Figure D-3. 
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function MouxttSootDisk ; Integer; 

var promptstr : String; 
okstr ! String; 
cancelstr j String; 
volStr ; String; 
gbvParams : PathnaraeRec; 

begln 

pronptstr •- .p lMee ^^ ^ 
okStr :- 'OK'; 
cancelStr :- -Shutdown 1 ; 

gbvParams.pathName ;- GvolEtr; 

GET_BOOT_VOL CgbvPararcs} ; 

M0UntB ° 0tDi ^ '- TLMountVolu** (174,30, 

prompts tr,volstr r 
end 1 ,- okStr, cancelstr) ; 



[begin Mount Boot Disk...} 



(string to appear in box J 
(title of OK button f^l) } 
(title of Cancel button (=2) J 
(define pointer to volume name} 

(find the boot volume name.) 

(Call Tool Locator's mount -volume. J 

(-.routine; it return., the number oL.) 
I -tne button user selects (1 or 2)} 

(End of Mount Boot Disk) 



Please insert the disk 
/SVSTfMDIShV 



jhutdown ) 




Figure D-3 

TLMountVolume screen display 

* £T, 23 ™°T VOlUme *"<* b0x sh °- i„ Figure D-3 i 



Check Disk Error 

CheckDiskError 



==ss:2BKEsra£ 
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I 



Cr.eckDisk Error Is In the source HI a 
D1AL0G.PAS, 



CheckDiskError notes whether the previous operation caused 
an error and, if so, pats up a stop alert and returns TRUE as the 
function result. Otherwise it just returns with a value of FALSE, 

•& input: CheckDiskError has a single input parameter: an 
integer location number that specifies what pan of the 
program made the call. Each call to CheckDiskError passes 
a different integer. The integers have no significance or 
purpose other than helping the programmer locate the part of 
the source code that generated the error. 



function CheckDiskError (Where: Integer) 

; Boolean; 

var itemClicked : Integer; 

ourAlert : A lert Template, - 
ourErrStr ; Str255; 
ourtthereStr : Str255; 
ourString : Str255; 
diskErrNum ; Integer; 



(Begin CheckDiskError...) 

(which button user clicks) 
{defined in DIALOG, PAS} 
(error number to display) 
(our internal error code) 
(error message) 
(error number) 



begin 

diskErrNum ;- ToolErrorNum; 

CheckDiskError :- (diskErrNum <> 0) ; 

ourErrStr :- 'XXXX'; 
ourWhereStr : - 'XX'; 
if diskErrNum O then 
begin 
Int2H« (diskErrNum, StringPtr( 

Longlnt (@ ourErrStr) +1) ,4) : 
Int2H*X (Where, St ringPtr( 

EongInt(@ourWhereStr)+l) ,2>; 
ourString :« concat ('Disk Error $' , 

ourErrStr, 
1 occurred at. S ' 
ourWhereStr, 

< i \ ■ 

■ t , 

MakeATemplate (@ourAlert,3ourString) ; 
InitCuroot ; 
it emC 1 ick ed : =StopAlert ( @ ou r Al e rt , N I L ) ; 



end; 



and; 



(Save the global error number) 
(Assign function result: 
— TRUE if error nonzero] 
{dummy chars, to set length byte) 
{dummy chars, to set length byte) 



{Get ASCII string of error no.) 

(Get ASCII string of our code no.) 
(Build our error message...} 



{Build a template for the alert) 
(restore arrow cursor) 

(Bring up the alert and take 
the user's input} 
(end of IF error nonzero) 
(End of CheckDiskError} 
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The alert box put up by CheckDiskError is shown in Figure 4-12 

Note that CheckDiskError calls MakeATemplate to define L_ 
features (text message and an OK button) the alert box will have. 
MdkeATemplate is described under "Constructing Dialog Bo 
and Alerts" in Chapter 4. 
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Appendix E 

HodgePodge Source Code: 
Assembly Language 



HP, ASM 312 
INIT.ASM 315 
MENU. ASM 324 
EVENT.ASM 330 
WINDOW.ASM 337 
DIALOG. ASM 353 
FONT. ASM 361 
PRINT. ASM 367 
IO.ASM 371 
GIOBALS.ASM 373 
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HP.ASM (main program) 



HotfijePmAje: An example Apple TIGS Desktop application 

Written In 65B16 Assembler by the Apple IICS Development Team 

Copyright (e} 1S86-B7 by Apple Computer, Inc. 
All Highta Reserved 



* This program and its derivatives are licensed only for * 

* use on Apple computers.. * 
" * 

Works based on this program Jtiust contain and ' 

* conspicuously display this notice. » 
• 

This software is provided for your evaluation and to * 

assist you In developing software for tho Apple IIGS ■ 

* computer, • 

* 

This is not a distribution license. Distribution of * 

this and other Apple software requires a separate * 

license. Contact the Software Licensing Department of * 

* Apple Computer, me. for details. • 

» DISCMIME R OF WARRANTY ( 
* 

* THE SOFTWARE IS PROVIDED "AS IS 11 WITHOUT > 

* WARRANTY OF ANY KIND, EITHER EXPRESS OB IMBUED, ' 

* WITH RESPECT TO ITS MERCHANTABILITY OR ITS FITNESS 

FOR ANY PARTICULAR PURPOSE. THE ENTIRE RISK AS TO * 

THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH « 

* YOCJ, SHOUU5 THE SOFTWARE PROVE DEFECTIVE, 10V (AND • 
NOT APPLE OR AN APPLE AUTHORIZED REPRESENTATIVE) 

* ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, • 
■ REPAIR OR CORRECTION. • 
* 

Apple does not warrant that the functions » 
contained in the Software will meet your requirements 

or that the operation of the Software will be » 

uninterrupted or error free or that defect? In thi « 

" Software will be corrected, • 

■ 

* SOME STATES DO NOT ALLOW THE EXCLUSION 

OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY • 
NOT APPLY TO YOU. THIS WARRANTY GIVES YOU SPECIFIC 
+ LEGAL RIGHTS AND YOU KAY ALSO HAVE OTHER RIGHTS 

* WHICH VAST FRCH STATE TO STATE. « 



ASM&5315 Code file "HP. ASH" — wain routine and COPY'S for other flies * 
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Version 1.0 — August 1987 * 



AB5MDH CM 
KEEP HP 

fKOFi HP. MACROS 



The U13ln program 

WaHjelDdge STMT 

using ClobalData 



I 

; Global equates used throughout tha program. 



True 

False 



g/equ 5BDO0 
gaqii 50000 



; 

; Set the data hank to code ban!! so t car use absoluta 

; addiresslrT. 

! 

phk 
plb 



Save address of D far use later 

tdc 

sti MyZP 



Load I nit everything. 



phi 

FiisbWord fSGOsu 

jsl Startuplools 

pla. 



pla 

one A 11 Done 
Jsr SetupMenus 



; Initialize system flags. 

r 

stz Lastwrype 
Kl QultFlag 
sti H'ndE* 



mode to uso for QD 

jNecessary bEcaiise 5tartUoTOOls 
;uee£ Pascal calling convention 
; leaving Input pa rams on stack 



HP.ASM Cmaln program) 



313 



Zero the print record handle. 

stz PrintReeord 
stz Print Racord+2 



Take events until user quits, 
jsr MalnEvent 



All ta done, let's shut down. 



AH Duns 



a nop 

jsl ShutDawnTools 

PushLeng PrintHeeord 
_DLaposeHandle 



Quit 


GuitParama 


END 




copy 


7/E16.WINDOW 


copy 


7/ El 6. DIALOG 


COPY 


INIT.ASM 


COPY 


EVENT. ASH 


copy 


MENU ..ASH 


copy 


WINDOW. ASM 


Copy 


DIALOG. ASH 


COPY 


FONT. ASM 


COPY 


PRINT .ASH 


COPY 


10. ASM 


COPY 


GLDHAL5.A5M 



,- get rid of print record handle 

I it Print Record has teto in It 

; dispose handle will fail but 

; wo don't care. 
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INITASM (Initialization) 



PI********* ********************* ********** ******** * * * * * * * * » ■ 1 * * * I * i 

HodgePodge: An example Apple IIGS Desktop application 



Copyright fc> 1966-67 by Apple Computer, Inc. 
All Rights Reserved 



A5H65S16 Code ills "IMT.ASK" — Toolbox startup/shutdown routines 



«■**+#■*•** + **#•***•**#■*** ft*** ft *#** ****-*****«**»**»**■*** *****■!* 

INI T. ASK 

Contains the lol lowing global data 
MylD Variable holding userld of this program 

TMsMode Variable holding mode used to start 

QuickDraw 
QrlgFort. Variable holding painter to original 

port that QuickDraw has vhen started up. 

Contains the following private data 

IS'Mr.aia Holds handle to memory -hat is used 

aa direct page tar the tools. 
iPPtr Pointer to above raefnory. 

Contains the following public procedures. 

function StartupTools (ModeToUse : 5CB_typel : integer; 

Starts up the coola Unitializing gulckdraw with the specified 
mode) and initial izea the global variables above. 

procedure ShutdownTools; 

Shuts things dawn, undoing wLnaL was done anove. 

Uses the HountBoctDisk dialog routine to have the user put the 
system disk on line. 

Haas the CheckTool Error dialog routine to cause a system death 
(bouncing apple) If the A register is ncntero. The x register is 
assumed Co contain a "Where" value. 

Change History 

June isb'I Steven E. Glass 
August 1981 Ben Xoning 

Modified to use the C calling convention so that can be used by 
both C and TMLEascal, (Input parameters are nnt removed from 
the stack.) 



INfT. ASM (Initialization) 3 1 5 



InitDmrmy START 

COPY 7/E1S.MEMCRY 

END 

»t«ii«mi.MiiUH»miitn 1 .....ii„Hi..Mi...i.M...«.ii 

Start upToola 

Input: ModeToUie — £0080 for 640 mode 

Output! ErrorCode — Error if nomera 

;note: different from c and pascal vehsionsj 

Calling Sequence: 

Pha ; space for output 

FuahWord I Mode ; Mode to use for QD 

jsl StartupTools 

P^ K ! remove Input parameter 

pla ; get func result 

bne MustQutt 

This Is a subroutine to load and startup all the tools 
an application generally needs. This routine also geta the 
space in bank lero that the tools use tor direct page. The 
only cine an error coda other than zero is returned is when 
the boot disK is not on line and the user asks to cancel 
rather than to put it on line. 

Order of work: 

11 Start 

Tool locator. Memory Manager, Mlsc Tools 
QuickDraw, Event Manager 

2) Whan these are running, the "One moment please" string Is 
displayed and Lc-adTools Is called. 

QuickDraw and the Event Manager are started up first 
because if the LoadTools call returns a VolNotFound error 
we need to have the volume mounted. This Is done with 
the TLKouRtVolume call which requires both OulckDraw and 
the Event Manager to be active. 

3] Next I start up 

Window Manager, Control Manager, 

Menu Manager, LineEdit, Dialog Manager 

4} After these are initialled, I setup and draw the 
meny bar and display a message to the user before I 
initialize the rest (Standard File, Font Manager, 
QuickDraw Auxiliary and print manager). 



StartupTools 


START 
using 


InltData 


HodeToUse 
ResultCode 


equ 
equ 


5b 
5-J 
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; 

; Direct Page use. The following equates 
1 describe how the direct pages are assigned 
; to the tools below. 



DPFor^-jlclsDrau 


aqu 


sooo 


DPF9rEveritMgr 


aqu 


5100 


DPFortt IHgr 


aqu 


$400 


DPForLlneEdit 


equ 


S5D0 


PPFnrMeirjMgr 


equ 


S6Q0 


EPForStdFtle 


equ 


$700 


SPForFontMgr 


equ 


$800 


DfForPrintHgr 


equ 


$900 



needs 
needs 
needs 
needs 
needs 
needs 
needs 1 
needs 2 



MalDB 



equ SKS0 



; Just in esse this routine Is called when the 
; data bar:* Is set somewhere else we set it 
; right here. 

phb 
phfc 
plb 



Copy the Input parameter Into the global 
data, area and Initialize the result code 
assuming all is well. 

Ids ModeTo'Jse,s 
Sta ThisMode 

Ida fO 

sta ReeultCode, 9 



t 

f Start with TiStartup 

; 

JTLStartup 



; 7nol Locator 



.* 

I Initialize the memory manager. 

; 

PUEhWord 4 

_MMStartup 

Id* tl 

jsr ChackToolError 

pi a 

sta MylD 



Initialize raise tools. 



MTStartup 
Id* tz 

isr ChecfcTool Error 
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First get some memory far the zero page we needL 

phi ; space for handle 

pha 

PushLcmg fTotalDP 

ttUtHMd MylD 

PushWnrd tat trflank+attrPage+attrFiiied+attrLoeiiBd 

PushLong 10 

_NeuHafidle 

Idx ll 

jer cbedtToolError 



Take the resulting handle (stiLl on the stacic) 
and dereference it, putting the pointer into 
ZPPtr. 



phd 




tsc 




tqd 




Ida 


[3] 


sta 


ZPPtr 


pld 




p .,-, 




sta 


ZPKandle 


pi a 




9ta 


ZPHandLe+i 



; save currant n 

; turn staeit into direct page 

deref the pointer 

we know that high word Is 

restore direct page 

; put handle into storage 



Nets that width gn startup Is 3ZD to allow doubling the 
screen width when doing best printing. 

Ida HFtf 

clc 

adc IDPForQuleJtDraw 

pha 

PushWord ThisMode 

PushWord t32Q ; ira* glie of scan line in bytes 

Pushword Myirj 

_QDStartup 

ldx *4 

jsr Chedtronllrror 

FushLong »0 
_GetPort 

PiUlLong OrigPort 

ldy I6« 

Ida ThlsMnde 
cmp t$B2 
beg okjnode 
Idy |J2C 
otorsode a nop 

sty y. :.'..•: 

Ida ZPFtr 

clo 

adc tDPFo^EventMgr 

pha 
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Pushword t20 


F queue size 




PUEhWord (0 


; x clamp low 




PUehWord MajlX 


; x claFp high 




Pushword #0 


r y clanu low 




PushWord (200 


; y claTtp high 




PushWord My ID 






_EM5tartup 






ldx ts 






Jsr CheekroolError 




Pot up a 


string telling user that 


something is 


happen! 119 


Pushword »20 
PushWord 120 
_MoveTo 

PushWord to 
_5etBaefcColor 

PushWord ISF 
_SetForeColor 

PushLong *Moment£tr 
_DrawString 






SbowCursor 




Make che 


LoadTools call 





I 

LoaaAgair. 



OkTaLoad 



_GET_FILE_INFO ParajnBloqJc 
bed QsCToLoad 

jsr Mount BootDiak 

emp 41 

beg LoadAgaln 



st a Res u 1 1 Code , s 
nrl Getwt 

PushLong iraolTable 

_loaaTccls 

bec ToolsLoaded 

ldx if 

jsr ChecltToolError 



(Try to find; the directory 

; '/SYSTEM/TOOLS/ . Ok? Co load. 

;Ilse, display psuedQ-dlalag 
(Did they select "OK""! 
.-yes, as try it again. 

(Else, they selected "Caneel", 
(So return result code 
(and leave this routine. 

;Fush address or tool table 
(Attempt to Ipaij them (should 
(work) . If ok j go on. 

(If error happened anyway, 
(we'll iust die here. 



,■ The tools are loaded so start them up. 

; 

ItMll Leaded 



an op 
_COAuj£Startup 



; QuickDraw Auxiliary 



WaitCursnr 



; With (jDAux started we can show the 
; watch cursor 



Pushword MylD 
_Wi fid St art up 



; Window Mans gar 



i ax I - ; 
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Jar CheckrDpl Error 

PusilLomj l?Q00Q 
_He f reshDe 5 It Top 

PushWard MylD 

Ida ZPPtr 

Clc 

adc tDPForCtLMgr 

pha 

_CtlSLartup 

ldx «a 

jsr CheektoolError 

Pushword MylD 

Ida ZPPtr 

clc 

ade (DPForLineEdlt 

Pha 

_LEStartup 

Ldx ts 

jar CneckTeolErxor 

PusbWprd MylD 
_Dlalog Startup 

ldx tag 

jsr CheckTool Error 

FushWord Mylli 

Ida ZPPtr 

Clc 

adc (DPForM^nuMgr 

pha 
_KenuStartup 

lax #11 

i*r ChecJtToolErrer 

_DesJ(St«rtup 

jsr ShawPlflaseHalt 

ldx <12 

Jsr CheckroolErrsjr 

PushWord MylD 

Ida ZPPtr 

clc 

adc JDPForstdFila 

pha 
_5FStartup 

ldx m 

jsr ChecxragiError 

PushWord fSfiODD 
_SrAllCapa 

PushWord MylD 

Ida Z-PFtr 

clc 

add IDPForFuntMgr 

pha 

_FMSra;rtup 



f display desktop 
; Contrc-1 Manager 



; LlncEdlt. 



; Dialog Manager 



f Menu Manager 



,* Desk Manager 

■ Me 5 saga for user 

; Standard File 



: display file names In all caps 
; Fent Manager 
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ldx 114 

jsr CheckToolErrar 

PushWnrd MylD 

Ida ?,PPtr 

clc 

adc tDPForPrlntHgr 

_PMStartup 

d* ►' \. 
jsr CheckTool Error 

jsr HidePleaseWait 

InltCursoj: 



Print KiiMfler 



reset cursor to arrow cursor 



All Is cor.e. He xusi. clean up the stack and get out 



Eetwt 

KomantStr 
K»tX 

ParaaBloek 



a nop 
plb 

rtl 



r restore dtor 
- all dene . 



str 'One moment please..." 
is 2 



PathNar.e 



dc 14 'Pathname' 

ds :■ 

ds 2 

ds 4 

ds 2 

ds 2 

ds 2 

ds 2 

ds 2 

ds 4 

str "/SYSTEM/TOOLS' 

END 



;ProDOS/ls Parameter block 

,-Hlth pathname as input; rest of the 

; fields will be set as output. 



• Pub Licl nit Data 

i 

' These are globa] variables available to the main program. 



JlfcllcIntcDATA DATA -Global 



t public 


Vari 


ibles 


MylB 




ENTRY 
ds 2 


ThlsMoae 




ENTRY 
ds 2 



OriflPort ENTHY 

rds 4 
END 
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InitData 

ZPPtr 

Tool Table 
ScatsTable 



EndTabl* 



PriuDflTA 
ds 4 
ds 4 

a nop 

anop 

dc 1 ■ (EndTable. 

dc i'l, 50101' 

de l'S,$0l01' 

do i'3, 50101' 

dc i'(,$01Dl" 

dc 1'5,$0100" 

dc i.'6,$oi00' 

dc I'll, $0103' 

dc 1'15,$01O3' 

dc J'16,$ai03' 

dc i- 18,50100' 

de l "19,50100 ' 

dc I'lD.soiOD' 

dc 1' 21,80100. • 

Ifc 1'22, 50102" 

dc 1 '23,50100" 

de 1'27,S01C'3' 

dc l"js, 50100' 

a nop 

END 



•StartTahlel/4" 
; too 



locator 
iBeniqry manager 
Jtllsc tools 
qulcJtdxaw 
desk manager 
event fnanager 
window raanager 
rcenu manager 
control manager 
qulcicdraw auje 
print manager 
line edit 
dialog raanager 
scrap manager 
standard file 
Font manager 
List manager 



» * * 4 r w ■ * A ** 



■**+#*» ***** 



*A »**»■.*** »*a 



***• * . ** - - . A , , i * , 



<•••*>•>» 



ShutDownTooIs 
Inputs; Hone 
Outputs: None 

Shuts down Bvery on,,,, statte<J „_ t _ InllToolfi 

* ' M •«**#****«,***.«,,,. 

ShutDownTools START 

using InltData 



_Dea)!Shutdovfn 

_FM5hutDown 
_PMs hut down 
_SFShuCDo«n 
_Dlalog Shut down 
_LEs hut down 
_MemiShutDown 
_wiRdShutDown 
_Ctls.hut.dovn 



JWShutDown 

_QDAuiiShutdown 

__DShutDovn 



; shut this first so that other tools 
; are still around (close DA's) 



; this is shut down after window mgr 
; because window mgr malces. centol 
; manager calls at shutdown time. 
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_MT£hutdown 

EushLong ZFHandle 
Dispose Handle 

EushWard MylD 
_MKSllUtdowr. 

_TLShutdovn 

rtl 

EHD 



; get rid of handle for dlrert; 
■ page 
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MENU.ASM (menus) 



Hodgepodge: An example Apple IIG5 Desktop application 



Copyright (el 13-B6-B7 by Apple Computer, Inc. 
All Rights Reserved 



A5M&S816 Code Ille '-MEND. ASM" — Menu initialisation and dispatching, 



* Menu i-_eT. ID's 



' " i * ■ * » * * - 



^••iiit*|«UIIM»H"-<- • - 



AppleMenuID 

FileMenuIB 

EditKenuID 

Kir.dowsMenu.ID 

ramsMer.uID 

UndoID 

Cut ID 

copylD 

FacttlD 

ClearlQ 

CloseWID 

About ID 
Quit ID 
openwiD 
Save ID 

Choose ID 

SeLupIC 

PrintTD 

ShowFontlD 

MonoID 



start 

gequ 1 

gequ 2 
gequ 3 
gequ '. 
gequ 5 

gequ 250 
gequ 2 51 
gequ 252 
gequ 253 
geqd 254 
gequ 255 

gequ 256 
gequ 257 
gequ 259 
gequ 259 
gequ 260 
gequ 261 
gequ 262 
gequ 263 
gequ 264 
end 



; These next S are standard and 
I required (or DA support under 
; TaskMaster. 



These are our own responsibility 



* ucHKiU 

* called when TaskHaster tells n-.e that a menu lte^. has 

* been selected. 
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Wtenu 



START 

using GlohalDATA 

Ida TasStBATA 

crop tZ99 

beq Unhilite 

bge DoWItem 

sec 

sbo #TJr.doID 

sbI a 

tan 

jsr (MenuTsble, jO 



; 299 is dumny do nothing - Ignore 

; do nothing 

; 300 and up are adders windows 



Dnhillte a nop 

PushWord (False ; draw normal 

PyshKord TasJ:DATA+J f which menu 

HllitaKenu 



rts 



HMnTibla 



;ir ■"[■ 
dc i 

dc i 

dc L 
dc i 
dc 1 
dc 1 



dc 1 



dc 
de 



dc i 
dc i' 



d^ 
dc 

dc 



ignore ■ 

ignore ' 

ignore 1 

ignore ' 

ignore ' 

doCloselteir. ' 

doAboutltem' 

domett Item' 

doOpenltem 1 

dosaveitenr 

doCtiooaerlten' 

doSetupItepi" 

doPrintltenT 

dDOpenlt-eir;' 

dOSetMano * 



Edit items 



CoWltem 



a nop 



frocassW 



sec 

ebc 1300 
ar.op 



In A is window number 



asi a 

asl a 

tax: 

Ida window 3 ist,x 

sta WhlchMindnw 

Ida wlndowlis£+2, x, 

sta whlehwlndo-w*? 

jsr dowindow 



times 4 to index window list 



jmp unhilite 
END 



; done with it 
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**" •■ ......... 



i a ■ ft ft -a b 4 



i*ta»«-tt 

* SetupHunus 



: arts^r* ** b¥ L ^ erting tiie ^ 



SetupMejrjs 5TART 

"Sing Menu DATA 



PushLong to 

FmhLmg If^tsJtenu " ""^ "* " tU " 

_NewMertii 

Push.Word I a 

_InsortMenu 



; space for retui 



PushLong to 

PushLong IKindowsKanu 

_NewMenu 

Push-Word (fl 

_IJisartMenu 

PushLong. tO 

Pushing (Edittfenu ' SPaC ' f ° E " CU ™ 

JtewMenu 

PujjhWord (0 
_lnjertMenu 

PushLong fo 

PushLong .m e Me ru ' Space '"» **"*n 

_Nen»!enu 

FushWord to 

_Inse.rtMenu 

PushLong #0 

Pushtoo Hippi^ta,, » space for r « U r n 

JtfewMenu 

PushWord #0 

_Ir.a«rtMeBu 



K2 ^r^r™^ to lnstaij * 

PushWord II 
^FixflppieHer.u 



FlnIflh oIf *"lng the ra e n u bar ready. 

PushWord *o 
_FlxMer)uBar 
pla 

.-niacard menu bar height 

PushWord #10 ,-_ 

jSetHTttleStart starting position o£ m&nu 

_ n rawManuBar . lrt . ,, 

.Actually draw the maim bar 

rts 



£Nf; 
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*Wn* E; Hoaa-W, Sec c«. : AsMmbv Languoee 



I ft • fr * ■ ■ * * - ft * * * * * * * «. * * * * • ■ * * ft * ft * ■ * ft* * + ■ * * ft ft* ft 4 ft-ft * * + ft ft* * ft #ft * *** 

1 AdrtToHenii; 

Use tho fact that the last SPOTF-FIUi returned in REPLY, record 

the name of the file and the state of the request, set PrlntAvail. 

14ft*»*ft* ft** ***************************** *****A*ftftftft-ft * * 1 * * I • * ft ft* 



ToMervj 



cpyidlp 



START 

using GlobalDATA 

Ida tl 

st a Print Avail 

pushlor.g ID 

_FrontWindow 

pla 

ata whic.hwlndo*' 

plx 

stx whlehwindow+2 

PUSHLQNG .0 
PUSHLONG whlcnwlndQW 
_Get*wefcon 

pla 

st a Tentphandle 

stx TempHaTidle+J 

jsr Deref 
sta 
stx 2 

Push-Word Windex 
FushLong flddgt 
FushWnrd n 
FustiWord ID 
IntZDec 



Ida 


iddqt 


ojra 


I'OO' 


sta 


iddgt 


ldy 


loLength 


Ida 


[01 ( y 


and 


■ISFF 


clc 




adc 


if, 


tay 




Id* 


I" 


Ida 


Idri, x 


sta 


[Cl,y 


tny 




Lv.y 




L nx 




inx 




epx 


IS 


bne 


cpyidlp 


Ida 





elc 




adc 


14 


tax 




Ida 


2 


adc 


10 


pha 





;Set PrlntAvail flag to allow printing 
;lt's the front window we're adding in 

;get result for pushing in a see, 
; space far result 
,-refcQj] has handle to data 



da reference 



; font's size 

,-ptr to string 

; length of string 

.-unsigned integer 

.-convert size Into an ASCII string 



rget names length 

,-flnd end of string to slide stuff 



; y index off ids is where wo store 

; x index off Idn Is where we load 



; do fi bytes 

;now pt, to itemlist lee. for insert 
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NotFlrstTime 



idn 

iddgt 

idcr 

iddmy 



phx 

PL'SHKDRD tSFFFF 
PCISHWORD tWlndowsMenuID 
_InsertHItam 

Ida w Index 
tone NotFirstTlae 
Pushword »299 
_DeleteMIteni 

Fushword »Sff7f 
PusbKord tWfhdowsftenuID 
SetMenuFlag 

Ida ITrua 

st a NeedToUpdate 

Ida to 

pha 
pha 

EuahWprd fWir.dowsManulD 
_CalcHanuSije 

Ida windex 

as: a 

ssl a 

tax 

Ida whichwindow 

st a WlndowMst,* 

tay 

Ida whlehwindow+2 

Eta WlndowList+2,)c 

ino windax 

Ida tamphandle 
ldx tsjnphaiidle+2 
jsr unlock 

it* 

dc B'\K3' 

dr c*00" 

dc il'13 1 

dc U«0' 

END 



; if first time, omit dummy 299 

; 2!*9 Is dutrany Iter to delete 
," it "a gone, now add next sn« 



re-calc siie 



r save off window Pointer for menu stuff 



,-*< for WIHDOWLIST Index 



,■ bump counter for ne*t add on 



ok, let this loose again 



nNSno" will slide in Behind it 
0D->15 slides Into nn 
and finally a carriage return 
a dummy so we slide exactly S 
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■ Hffiu Data 



DMA 



Aetuin eqj ■ 



AppieMenu dc c'»8\XH' , 1" AppleHer.uTD' ,11'RETURN' 

dc c' --About HotigoPodge...\h:' ,1" About ID', 11 'RETURN 1 
dc c'—\H500D\0' ,11 'RETURN ' 
dc c ' . ■ 

EditMenu dc c'» Edit \DfcT , 1 'EdltMenuip' , il ' RETURN" 

dc c ■ — Ondo\ »liH' , 1 ' UndoTD ' . 1 1 ' RETURN ' 
dc c'— \N500D\C',11*HETUW1' 
dc c'~Cut\ l ')(xH , ,l , ctitrD , ,il'REruRN' 
dc c ' "Copy\ "CcH ■ , I > Copy ID ',11' RETURN ' 
dc c — Paste\*VvH" ,1 ' PastelQ ' , il 'RETURN ■ 
dc C— Clear\N',l'ClearID', il'RETURN* 
dc c ' . ' 



FllnM«nu dec 1 )) File \H' , 1' FileMenuID' , 11 ■ RETURN ■ 

dc c'-'Open.. . \*OcH', I'OpenWID' , 11 'RETURN' 
de c -=cjgse\DHM' CloseWID', 11 'RETURN ■ 
dc c'—Save As. . . VDH',i 'SavelD' , 11 'RETURN ' 

dc c . VNSODD^C'.il'RErURf;' 

dc c~choosa Printer.. . ^H'.l'ChoraelD' , il'RETURN 1 

dc e'--Page Setup. .. \DH M 'SetupID' , 11' RETURN' 

dc e ■ --print... \D"PpnM' Print ID ',11' RETURN' 

dc C— \NS00D\&', 11 'RETURN 1 

dc C -- Qult\ *QqH< , 1 'QuitTD \ 11 ' RETURN ' 

dc c ■ . ■ 

Kin.dnvsKenu dc c'» Window \DH', i 'WlndowsHenuID' , il ' return' 

Drtgltm ENTRY 

dc c"«No Windows allocatedSN2S9' , 11' RETURN' 



PontsKenu 



lie c'» Fonts \H ',1' Font sMenuID', 11 'RETURN ■ 

dc C"— Display Font. .. \*Ffh" , 1' ShowFont ID ', 11 ' RETURN ' 



KonaP?cplteni 



Mono St r 
PropStr 



ENTRY 

dc c'—Dlsplay Font as Mono-spaced\*I*nU', 1 'MonoID' , Il'RETURN' 

dc c'.' 

dc c'~Dlsplay Font as Mono-spacBd\H',l 'HonolD' ,11 'RETURN 1 

dc c'~Display Font as P report ionalVMttK', 1'MonoID" ,11 'RETURN' 



'•"""KtXTE: 300 Is starting number for a building list - used in AadToHenu 
'***** 299 is trie dierjny one that is deleted when we get a real one 



END 
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EVENT.ASM (main event loop) 



JtodgBhttgtt An ««, flppl6 IIGS ^^^ applic;3tiDn 

copyright (c) 19B6-B7 by Apple Computer, X RC . 
All Rights fteaerved 



ASM65S16 code file "EVFnt asv" _ t^-i,** . 

""■ AS!f TasAMastar call; Dispatching to a n 

other routines? Menu diimlng. 



••St,,.,.,.,, 



»#****#* ■ 



*****»■(**#* 



»l»*fet*fjtt1 



Event 

This contains the main flvent ioop- 



KalnEvent 
Again 



M#n* * , . . , 



**«•#*«**»«*•*♦»****»»* ..,.„.. 



START 

using GlobalData 

anop 

Ida QjiiCFlag 
one All Done 

jsr CheekFrontW 

PushKord td 
PushWord tSFFFF 
PushLong lEventHecord 
JTaskMester 



,'Has Quit been select? 
.*..- if so, stop the loop, 

,-flandl.a the menu dis/enabLe 





pla 

fc»q Again 




asl a 




tax 




Jsr [TasfcTable,*) 




bra Again 


AllDone 


rts 


TaskTable 


anop 


f Event ma,na 


ger events 



;Ko event? loop. 

,' Multiply by two,. . 

;use for index lnto„. 

.-dispatch table to execute events 

;L3op, 



de i ' ignore ■ 
etc 1" Ignore 1 
dc J ' ignore * 
dc 1' Ignore 1 



; null 

; 1 mouse down 

7 2 irouse up 

; 3 key down 



33D 



Appendix E; HodgePodge Source Code: Assembly Langua 



9e 



do i" Ignore" , 


4 undefined 


1c 1' Ignore" i 


S auto- key down 


dc i' Ignore' 


6 update event 


dc i ' ignore ■ 


1 undefined 


dc i 'DoActlvate' 


8 activate 


dc 1" ignore' 


9 switch 


do 1" ignore 


■ 10 desk ace 


dc i" ignore" 


■ 11 device driver 


do i' Ignore" 


■ 12 ap 


dc i" ignore" 


■ 13 ip 


dc i ■ Ignore ■ 


: 14 ap 


dc 1 * ignore ' 


■ 15 ap 



Task raster events 



dc I "Ignore" 
dc i'BoMenu" 
dc i ' Ignore ■ 

dc l'tgr-ozE' 
dc 1" ignore 1 
dc 1" ignore" 
dc I'DoCloselt* 
dc i' Ignore" 
dc i ' Ignore ' 
dc i'DoMenu' 
dc 1" Ignore' 
dc 1 ' ignore ' 
dc 1" ignore" 



in desk 

1 in MenuBar 

2 in system window 

3 in content of window 

4 In drag 

5 In grow 

6 in goaway — sajnE as "Close" 

7 in InoEft 

8 in Info bar 

9 in special menu item 
ID in openMCA 

51 in frame 
in drop 



Item 



END 

&+#*.#+****++*+*******:*-*#**#**•*•#***•******••******************» 
■ 

' OiecJtFrcntW 
■ 

' Checks to see if front window has changed and if 
' sc deals with various menu enables and disables. 
' call id by main event loop, and activate event a. 



i. *■*.**. . ** ■ ■ k * ****** *+****+****±±±±+* 

ChaekFrontW Start 

using MenuData 

using GlobalData 

pushLong 10 
_FrontWlndow 
EullLong rhiswindow 

Ida ThisWindow 
crap Lastwindow 
bne changed 
Ida ThisWindow +2 
emp last Window 42 
bne Changed 



**+***«» *•*****«*•***** 



Eiitl 
Changed 



Cta 

anop 

Ida Ihisttindow 
at a Lastwlndow 
Ida ThlaWlndow+2 
Bta LastWindow+2 

]sr TypeThisW 

Ida ThisWTjrpe 



;get the current rront window. 

; Check to see If it is 
,-stlll the same window as 
;last time 



;Ho Change No problem. .. .Else, 
?LastWIndow :- ThisWindow 

;3et ThisHType-type of the new front win 
;arrlvlng here, the window has changed. 
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crap LastWType 
beq Exitl 

!ofc so start changing menus 

ciap ID 

one There lei 

jar SetupForNoM 
bra FinishUp 



Therelsl 



NotSysW 



AHOP 

crop #1 

one NetSysW 

jar SetOpForDaW 

bra FlnisMJp 

Jsr SetOpForAppw 



! And drop Into exit stuff 



Flnlshnp 



RcallyDone 



Ida WeedTotlpdate 
beq ReallyPone 

_Drai*tenuBar 
stz NaedToUpdate 

Ida ThlsWType 
sta LastWType 

rts 



jit's, type may not have changed. 
/Branch taken If the latter is true. 



; Is there a front window 
,-take this branch If there Is, 

;if no front window then disable 
; various thing I care about and go 
; Finish up 



;ls it a system (Da) 
; taken if not. 

;eisa it ia a da. do what's needed 
;and do the exit stuff 

;A-reg - Wtype. Go deal w/menu stuff 



;has tbe menu bar changed 
; taken if not. else 

;we need to re-draw the menu 
,-and say we did it . 



; LastWType :- ThlsWType 



• figure out the type of the front window. 

* D- their* is no window, 1 - It's * da window. 2 - App Font Win. S- App Pic Win. 

TypeThlsW 



DoneEarly 
WasApp 



a nop 
Ida ThtsWlndow 
era ThlsWlndow+2 
Sta ThlsWType 
beq DoneEarly 

Pushword to 

fushLong ThlsWifidow 

_GetSysWFlag 

pi a 

beq WasApp 

Ida II 

ata ThlsWType 
rts 

Anop 

PushLong tD 
PushLong ThlsWlndow 

_G«twirerCqn 

pi a 

sta Temp 

plK 

StX Temp+2 

jsr deref 

sta , 
stie 1 



;was there a window at all 7 

,-lf no front window then ThiaWtype-O 
; taken If there really was no front win 

.-get and save wuther or not 
fthlH la a 

; system window or not . 

;0 means not a sys window 

;lt's a sys (da} window so 
;sat lastwtype - 1 



;It's an app win. find out what Jclnd. 

; space for get ref con in a sec 
(■else i ha ire the window ptr 

;get refcon it has handle to data 

,-recon handle to 
;tesr.p and A/x 



;loek. It down for a sec 
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idy 


(oFlag 




Ida 


[01. y 




beq 


PicW 




Ida 


*2 




Eta 


ThlsWType 




bra 


QuttaHere 


ilea 


Ida 


13 




eta 


ThlsHType 


OuttaHere 


Ida 


Temp 




ldx 


Temp+2 




jsr 


Unlock 




rts 





; check If pictura 
.-get window type 



;lt's a font window bo. 
;say so and 

; split 

;lt's a pic window, so 
;say so and split. 



; unlock the re f con hand! a> 



Tamp 



Thisifindow ds 4 

last Window ds 4 

END 

•■!**■ ***•»■**■• • **#* + #*##*«»-**#*##*#*#*#*#***■#*#•■*•*********** 

* doQuitltem 

* Set* quit flag. 



doQultlcem 



START 

using GlobalDAtA 



Ida (True 
sta QultFlag 

rts 

END 

***#**■#***+»■+»**.******■»■•***'•**#**#**#** a********** *********** 

* Deactivate 

* 

■ Handles activation of windows and adjusts the edit meuri 

* based on window type. 



DOftCtlVate Start 

using GlobaLData 



and 



ida EventModiflers 
and fl 

beq end 

jsr CheckFrontW 

rts 

END 



■'don't care about dEactivate- ? 
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■***»***< 



****+*■**«****»*«*# 



' - - * - ■ ' ' 



• ft ft** ..,.*** 



* SetupfarAppW 

4 

* Sets the edit menu Items up lor the application windows 

- ttiat Is disabling them, knd sets the other file menu items 

* accordingly. 



ft #*# * ft * * i 



NoSaveEnabla 
Cont 



»** * ***** ******* * * i ■ * » . 
SetUpForAppw Start 

Using GlobalData 
Using MenuData 

EushLsng 10 
PushWord f Save ID 



Ida ThisWType 

ctnp t?. 

bne NoSaveEnable 

PushWord (True 
bra Cent 

PushWord tFalse 

PushWord tcioseWID 
PushWord IT run 

Ida PrlntAvall 
beq. SfclpPrint 

PushWord IPrintlD 
PushWord ITrua 
PushWord tSetUpID 
PusbWtord (True 
>r ChangaMltems 

ida LastWTypo 
emp (1 
bne Exit 

PushWord tSOOBO 

PushWord #£aitMenulD 

_SetHenuFlag 

Ida (True 

sta NeedToupdate 



ft * i * ft ft* * * * * * ft iM»itni««^ ITI1 



,-get ready to call changeMitems 
;we gonna do save item, but we need 

,-tc figure out whether It should be 
(enabled or not, is it a font window ? 
,*1E so dont enable the save item. 



;else push true Tor enable 



SkipPrint 



;was it a da last 7 

,"i£ not we don't need to do what a next 

; disable edit menu 



,-set update flag so I nnly redraw 
;the menu bar once 



Exit 



rta 

END 

• l».MI.<.... ,„.•...„« .....Ui.i,. 



************** 



* EetUpForNoW 

* 

* Sets the edit menu Items up for the desk ace window; 

* that is enabling edit menu, and close in file menu 
» accordingly. 



************ 
SetUpForNoW 



" *'"HtiWtli..«.,n.. i.*,IH*.i 

START 

Using GlobalData 

Using KenuData 



PuehLong *o 
PushWord t Save ID 
PushWord »False 



;end of list mark first. 

,-disble save 

;i desire disable. 
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Puslrttord IPrintID 

PushWord I False 
PushWprd tSatUpID 
FushWocd IFalsa 
PushWerd. IClose-wiD 
Puahword fFalse 
jsr ChangeMItems 

Ida LastWType 
crap II 
one Exit 

pushWc-rd I SO 080 

PushWotd lEdltMenWD 

_SetMenuFiag 

Ida tTrue 

sta NeedToUpdate 



,- enable 

,-what was it last 

jmi !i a da last 7 

;if not vie don't need to do whata next 

; disable edit menu 

;set update flag so T only redraw 
;the menu bar onco 



Exit •- - = 

End 

MM ** # * ******* * iii 



* SetupForuaW 



e **********+***********»+ **•»**********• 



* Sflta the edit menu items up for the deslt ace window: 

■ thit Is enabling edit rnEnu, and close in file menu, 
' accordingly. 

i 

■*..*.**»**»**»***•»**•*•»•*■««•»»*** *»"«*******•■■*«"**■***«*** 

SetUpForDaH START 

using GlobalData 
Using MenuDaca 



push Long 10 
pus [Word *SaveID 
PushWerd fFalse 
PushHard 'Print ID 
PushWord tFalse 
PushHofd isatUpXD 
PushWord (False 



;end of list mar* first. 

;dlBbl« save 

;i desire disable. 



PushWord ICloseWID 
PushWord IT rue 
]sr ChangeMItems 

Ida LastWType 
emp II 
beq Exit 

PushWord «$ff7f 

PushHord lEdltManuID 

_5etKenuFlag 

Ida 'True 

at a NeedToUpdate 



; en .it", a 



;what was it last 

;*as it a da window last 7 

fit so we don't need to do what 6 next 



; enable edit menu 



; set update flag so I only redraw 
,'the menu bar once 



Exit 



EOT) 
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* C.1if.qsy.ltsn;s 

■ 

* Enables/Disables the various menu it 

* flags pushed on stack, 

* 

* Entry Stack Looks like: 

* 

* ItemID 

* Enab la/Disable FUg 
* 

* IteralD 

* Enable/'Disabie FUg 



■bis according to the 



;long indicator of end of LffijT;. 

;word item id 

; (word) true - enable 

;«£>rd item id 

; (word) true - enable 



Return 
Sp -> 

.angeMItems Start 


i******* 


******* 


;word 

******** ****At**ti 


■******■ 


» 




PullWord 


RtaTemp 




;save 


return 








1 


Ida 3, a 
beq Dene 






; check 
;li so 


for and of 
split 


Hat 


n.-i 


r* 



DoEnibla 



Don* 



pla 

bne DoEnable 

_Disa.bleMI.tem 
bra Lp 

_EnablaMltejn 
bra Lp 

PullLong 

PushWord RtaTemp 
rte 



ftaken if ve should enable items 

;alie disable them 
;sr.d start over 

; enable item 
.■ens more time 

;pull end of list mark 

;push return address 



RtaTemp 
EnableFlag 



ds 2 
ds 2 



END 
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WINDOW.ASM (windows) 



iittnti * ■ -ii ** *** & ** * ft • 1 1 1 * *#+ #*# • * ft 



■ Hodgepodge: An Example Apple JIGS Desktop application 



Copyright (c) 19B6-S7 by Apple computer, Ir.c* 

All Rights Gtese-rved 



fcSM65S16 Code file »WIN,XW,ASM" — Open/Close windows 



ft***i * A .> »***#■* + * + **■*:** ft »■*»■********** * ***■*■•**■**■•« n 

■ 

' KLdeALlHircdows 



************* 



lit ft ft ■ * * * * * * * * * ******** ****** ■ ■ 

MideAllWindows STRHT 

using GlobalDATA 



HldeLoop 



doKld 



st i VIndeje 

FushLong ID 

^FrontMindow 

Idx vindex 

pi a 

st a VTabLe,* 

pla 

aLa VTabL« + 2,x 

cmp #a 

bne dob Id 

Ida Vtable.x 

bne do-i i d 

rts 

phB 

Ida Viable, x 

pha 

_Hid«Wi.r.dow 
Lda Vlndex 
clc 

aac 14 
sta VLndcx 
bra Htdelioop 

END 



r**ft*ft*ftft* ■ ■* * ■ ******** * * * * ******* 

; Index for Hat of what was vis. 
;hlde 'em all, looks neater 



;all vis, windows hidden now 
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ft*******!**************** t.l.,.>..,..l...t., »••!„>. 

DoOpenltem ; 

1) Hake sure not too many windows open already — may show dialog 
2\ Call AddTeMenu ta add Its name into the "windows" menu Hat 



********* *********** ****+**-*« 



****** ***■*#*****•■**„*»#*. ,*«,m 



DcOpenltem 



START 

using GlobalDATA 
using FontDATA 





Ida wlndex 




cmp tlastWina 




bee OkToOpen 




jsr KanywlndDlalog 




sec 


Don* 


rta 


OJsToOpen 


)sr OpenKlndow 




bcs Qone 




jmp AddTofcenu 



END 



f Check if ton many windows open already 
,-... otherwise "window" manu overflows! 
;No, ed go ahead and try to open one 
;yEs, so confront user with dialog box 
?Set carry becaust it didn't happen 



lit we didn't open, don't add it 
;Add it to the menu list and exit 



" Eosaveitem : 



* + **»*#****** *■•■****.*#*,»****». m i# + il 

DoSaveltem START 

using Gl aba ID ATA 



■ *******■*»**•*■****■»** 



push long to 

_FrontWlndow 

pla 

at a whlcnwlndow 

pile 

stx whichwlndow+2 

FUSHLONG tO 
PUSHLONG whlchwlndow 
_GetWrefCon 

pla 
P l* 

jsr darer 

sta D 

St a Aefptr 

stx. 2 

■tK Refptr+2 

ldy toFlag 
Ida [0],y 
beg oktosav 

rts 



(it's the front window we're saving 

,'get result for pushing in a sec. 
7 apace for result 

;refcon has handle to data 



; check if picture 

,-save only type windows 
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OK'JIMV 



Btwitoff 



PUSHLONG tO 
PUSKLONG whlchwlndow 
GetWTitla 

pis 

eta HamePtr- 

plx 

stx NamaPtr+2 

PushWord #20 

PushWord t2.0. 

PushliOitg tEromptJ 

Pushleng NancPtr 

Fushviord 115 

PuahLong I reply 
_SFPutFile 

Ida r_good 
bne Savel-Dff 



Knap 

JfaitCursor 

Ida Reiptr 
■ta D 

Ida Kafptr+2 
sta 2 

lay toHandla 

Ids [0],y 

sta PlcHsndle 

iny 

iny 

Ida [0],y 

eta PlcHandLe+J 

Ida PicHandle 
id* PicHandle*Z 
jar Deftaf 
sta PieDestOUT 
stx PicnestouT+3 

Ida »R_fullPN 

sta MamaFtr 

Ida l-R_FullPH 

lit a Native Ptr+ 2 



;spaqe for result 



x Loc 

y loc 

prompt string pointer 

File nair-e 

Max file name length 

reply list result 



o t> means OK to load St 



this de-refd» la the data to write cite pichar.dle (we'll de-allocate) 



7 now pointing tn what we write 

; put pointer to name in l/o pa ram block 



nc-pac.t 



Jar SaveOne 
Bca OuttaHera 



'lx Hi- 



lda refptr 

clc 

ade foLength 

Sta 

st a refptr 

Ida refptr +2 

adc 10 

Eta 2 

st a refptr+2 

Ida x Fnajr.e 
and I SO OFF 
tay 



; now fix up name 

f where the name will go 

F save in C,2 also for later indirect 



WINDOW.ASM (windows) 



339 



Cpy-IT 



sep iioaiDDDaa 

longa Off 
Ida r__Fnajne,y 

st« [o;,y 

dey 

bpl cpynm 

rap ttooiooooa 
lenga on 

push long refptr 
pushlong whfehwindaw 
setwritle 



,* (It points to string now, remember?) 



Ida ID 
piH 

pha 

Pushword twlndowsMenu'd 
CalcMenuSlze 



re-eale size 



OuttaHere 



Ida picHandle 
Idx PieKandle+2 

lex Unlock 



:rit viTifif 



refptr 



ttS 

ds 
END 



<9rt«tti + iiliit**tt«*4fcik*444l it * * * * * * * * ■**■*** 



I IriTtTT A ****▼"< 



* QpenWindow: 

* 

* 1) Call SFSETFILE to get name of file to display in window 

* (or the dialog to select font If Display Font call) 
* 

* 1) Gets memory for, and loads the pleture^font data Into memory 
* 

* 3) Allocates a new window 

* a) puts handle to HyWlndowlnfo in WrefCon 

* bl note that routine to draw picture contents is set to "PAINT" 

* c) note for font draw contents Is "DJSPFONTHrNDCw 

■ 

* The definition of KyWindowlnfo Is contained in global data 

i 

* If the menu manager is being used to add ltemllst Items with the file 

* naice. It will squeeze the \H etc. together (see AddToMenut . In any 

* case, the file name string lor the wlndDW title can still be found 

* starting at this area+5 
• 

* returns j carry set - didn't open It (user cancelled SFGETF1LE) 

* carry clear - window opened 



OpenWindow 



STMT 

using GlobalDATA 
using iDData 
using Font DATA 
using HindowData 



stp 



Ida TaskData 

cmp tShowFontID 

cr.e A si: User 

jsr DoChcdseFont 

bcs stp 

jnp DoTheOpen 

rts 



is it open for font window? 



; cancelled choose font 
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* call SFGF.TFELE to request the file name 



AaUTser 



HancLleError 



*m*»*ii*a 



Ida 120 
ptia 

Ida (20 

pha 

PushLong IProenpt 

PushLong IcpenFllter 

PushLang 10 

PushLong ireply 

_sfGelfl la 

Ida r_.ic.od 

bne loaditup 

aec 

res 



' Get apace for the picture file 



; x loc. 

; y loc. 

; prompt string pointer 

,- Do dimmed display of unloadables 

; list of types to include — for all 

; reply list result 

; OB means OK to load it 

; carry set return: didn't open 



tttn *i * 



load! t Up 



ar.Gp 

PushLoiiq fu 

FushLang tSBDOO 

PushWni-d My ID 

FushKord tsOOOO 

FushLong fO 
NeuHandle 



; space 

,* size 

; ^ 

; no restrictions 

,* loc not Important 



DoTheQpen 



pi* 

St* PicHandle 
pi* 

stx FieHandle+2 

bcs HandleErrer 

jar Derei 

9ta PlcDestlN 
st* PlcOastlNtZ 

a nop 

PushLong ID 
PtfihLQng »MyHlnro$lze 
PushWard MylD 
PLifihWord ISCDOO 
PushLong 10 
New Handle 



7 if error occured from no handle 

; darefanca handle (in a,*} 

; put pointer in i/o parara block 



,■ space 

; size 

; Id 

; fixed and locked 

; loc not important 



pla 

st a re f con 

plx 

stx refcon+2 

bcs HandleError 

]sr dcref 

sta refptr 
sta 

stx rafptr+2 
stx 2 



;da ref. for storing stuff Into 
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ft-n.±ij*-*±£it 



* Start by assuming this will bo a picture window (not a font window) , 

* We set the address of the drawing routine to PAINT and set the flag 
» in MyHindDwlnfo record to Indicating picture. 



■ * * * * i * * * 



Ida IPalnt 

st J DrawRtn 
Ida * "Paint 
sta DrawRtn+2 
ldy toFlag 
Ida 10 
sta [0| , y 



; first the address of the Paint 

; routine 



; Now set the flag field 



; Now ue see if that silly assumption above was correct. 



Ida TaskData 
cmp tshowFontlD 
bne set ID 

Ida #1 

ora ManoFLag 
sta [0], y 

Ida DesiredFonf 
sta PicHandle 
Ida DeslredFont+2 
sta PicHandle+i 



look at the cienu item that 

brought us here. 

not the font one so go on 

fix the flag field. 
set bit 1 if mo no spa cod font 
(Y still set) 

put the chosen font Id where 
we will later put it in 
the MyWlndowInfo record 



Ida (DiapFontWlndow 
sta DrawRtn 

Ida fDispFontWlndow 
at a OrawHtn+2 

jBip DoMovUam 



finally, flu the pointer to the 
drawing routine 



Set 10 



Ida m_fullPN 

sta NajnePtr 
Ida l*B_PullPN 

sta NaroePtrf2 



put pointer to name in l/o param block 



load picture in "(iamePtr" into "PlcDest" 



**■*«>*** 



jsr LoadOne 
tacc DoMovMaui 



load It 



lOError anop 

PushLnng RefCon 

_DisposeHandle 

PushLong PieHandle 

_Dlspo.se Handle 

sec 

its 



There was an error loading the file 

so dispose of the memory that we 
allocated while trying to create 
this window 
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*4*YTT** 



* Hove the files name into the param bloeic 



tMli«f«*« 



DntoiiKar, 



Ida refptr 

Sta 

Lda re£ptr+2 
sta 2 

Ida plehandle 

ldy foHandte 

sta 10] ,y 

tny 

' r.y 

Ida plchandle+J 

Bta [0|,y 

ldy loBlank 
Ida I' ' 
Eta [0|,y 



.■use zero page far indirect: stores 



;inta the recfun area (refptr) 



t Put blank In record at blank field 

; (note this 14 bit store will over- 

; write the length field but we don't 

; care since we fin It below. 



NjmeLenOit 



npynn 



lda refptr 

clc 

adc (DLengih 

sta wlndaddr 

sta 

Ida reipfcr+2 

jdc 10 

sta wlndaddr+2 

sta 2 

Ida r_FJiam» 

and (500FF 

onp fMaxMameSi ze 

bjnl S'an-.eLenQK 

Ida ♦ Ma it HameS 1 ze 

sep t *00 10000 

sta r Fname 

rep 1100100000 

tay 

sep t *001 00 00 

longa off 

Ida r Fname, y 

sta toi,y 

dey 

bpl cpynm 

rep 1*00100000 

longa on 

ldy ♦',':•: 

ldx 1640 

sLK Datawldth 

StX mew 

sty IsliP(?3*G 



where the name will go 

save In 0,2 also for later indirect 



; adjust max six 

; adjust pixel count 



; Jet up the DataHelght based on the type of window it Is, 
; 

I Ida II BB ; assume picture and raake 200 the max 

sta DataHel^ht ; height 

Ida BefPtr ; now see what It really Is 

sta 

Ida RarPtr+2 

sta 2 
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Ida TasJcData 

□up ICJperWTI: 
bne NotlsPlcture 
juip IsPietuxe 

PushLong OrigPort 
Set Port 



NotlsPicture PusftLong to 
JSetFontlD 

ldy »oFontlD+2 
Ida [0],y 
pha 
dey 

dey 

Id* [0],,y 

pha 

PushWcri 10 

_lnstallFont 

PushLong I PI Record 
_GetroMlnfo 

P i:5;"ii. ::>nq ID 

Ida iSL-S.T". 

clc 

adc Descent 

pha 

PushWord fNumLines+2 

Jtuitiply 

pi* 

sta Dar 4 Height 

pla 

}sx FlndMaxWldth 

Pushtord »c 
Installment 



; Use the original, port obtained during 

; startup to sutE sura a port Is sat 

; for the following text sl?e calcs 

,- save this on the stack 



; now instill the font that will 
; be used in the currant port 



; get the font Info so can get 

,* ascent and descent, 

; space for result 

; now multiply sum of ascent i 

; descent by nun lines to draw 



; put result In DataHsigfrt 

; atrip off high word of nothing 



; using aaved font Id on stack 
; re- install tfte orig font 



IfiPlcture 



a nop 



* offset upperleft corner for opening of window 

ldjt to 
MoirOff Ida IsUPos,* 
clc 

adc wyoifset 

sta 5i:?os,i 

Ida ISlzPos+2,j( 

clc 

adc Wjioffset 

sta SlsPos+Z,* 

inx 

irut 

Inx 

lnx 

cpx ie 

bne MoirOff 



Ida WxOffset 

elt 

adc 120 

sta KxOffset 

Ida HyOffset 



; adjust offsets 
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itoYiet 



ele 
ade 112 

cmp 1120 
bne Dorset 
Ida 412 
st a My off sat 



;lf ve get too low, start at top 



* flow, finally, create the new window 



,|1.P*T*1 ■ 



iitally 



Pushiong. (0 ; Space for result 

pushiong (HimJoviParaiiiBlccfc 
ttewHlndOH 



pla 

sr_a whlchwindow 

pla 

sta vhieh.winilow+2 

PushLang OrlgPort 
_Sei_Port 

Ida PicHindle 
idit PleHandle+2 
jar Unlock 



LTse the original port obtained during 
startup to malto sure a port Is set 

unlock handle 



........ «* 



♦ Force origin boundaries (see Manual definition of Window Mgr's SetDriginMasij 



t»>lllliM 



Pushword #SFFFE 
EuBhLong which* lndow 
_Sec_orlglnMasl( 

clc 
rts 
end 



; carry clear return: we opened It 



1II,t4|l4i * - ■ •,*»*»»•*******»********■* A*-.***.***. ********* ****** 



1 MndowData 






^.•,MM ,il..l» T .T»*»i*l.Htll«l»1i*tTI**tM*' 

Wiri»2i'.3 data 

Wlr.oaMParajr.BlacH a nop 

dc 12■Ml^dowEnd-Wi!ldowparaIlfflloc^l■ 

dc I?,' FTitle+FClose+FP,Scroll+FBScroll+FG^ow+Floc^I+FMave+FVis■ 

Ptr to title 

RefCon 

Full Size (0= default) 

Color Table Pointer 

Vortical origin 

Horizontal origin 

Data Area Height 

Data Area Width 

Max Cant Height 

Ma* Cont width 

Nunber of pixels to scroll vertically. 

Number of pixels to scroll horizontally. 

Number of pixels to page vertically. 



■indaddr 


dc 


tl'O 1 


r«fcon 


dc 


14 'u 1 




dc 


IZ'0, 0,0,0 




dc 


14' 0' 




dc 


iZ'O' 




dc 


12-0' 


Data Height 


dc 


i2>zaa' 


DataWidth 


dc 


12" 640' 




do 


i2'200> 


McW 


dc 


12 h 640' 




dc 


I2'V 




do 


12'1&- 




r.ir 


U-aa- 
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de Ifl'O' 



dc 12 

dc £4 



Draw Rt n 



WindovEncj 
ftefptr 



FlSecord 

Ascant 

Descent 

leading 

WldMa* 



dc ifl>oi 

de 11 'Paint' 

d <= ii'OrOjCD- 

tic U'SFFFFSTFF' 
dc H'o- 

anop 

ds 4 



J'^o.iD.aD.aso 1 



Info bar height 

SeiProc. 

Boutin, to draw i, ftl . ^ 

Routine to draw content 

Size/pos of cent ant 

Plane to put window up l n 

Mdreea ror "*«*»•■ «»«J I0 to .Heat., 

fwtafl points to j Q 

.SllE/p OS of CC . ntent 



■nop 

d 5 a 

ds ? 
de 2 
ds 2 



^"""^ — - - 

* Ope nFi Iter 

ft 

0= *"try, the etic , leok- UJce this; 



previous contents 
space for rsEult 



1 



I word 



^iote^^dl^ctprv J^T | ion. 



return address 



** ■* ****, 



°penFIlter 



f 3 bytes 
, 1 

I <- Sp 



start 

using GlohalData 

Pftb 

phlt 

plb 

pi a 

ata RtnAOdr 

pla 

st a RtnAddr+2 

tdc 

st a DPSa^e 

Ida ffyip 
tod 

pi a 

St a 
pia 
sta z 

Ids ti 

idy #s 10 



' a * L DBR b »cJ( to this banfc 



*ave the return address 



; save the ROM's 2p 
.' and swap l n OU jr 8 

; now flet the pointer to the 
' directory entry 

■ Aasum * vlHible and dimmed 
' look at the lUetype byte 
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BoTPicFile 



DFSave 

ItnMdr 



Ida [0|, y 

and »50CFF 

cmp #SC1 

bna MotEieFlle 

Id* 12 

turn 
sta 1,9 

Ida I}?Save 

ted 

Ida. EtnAddr+2 

pha 

Lda Rtr^ddr 

pha 

plb 

rtl 

ds 2 
ds 4 



; don't Jon* at the entire word 



; pass on ill other! 

; s!idw It as a selectable entry 



; pass it back do the stacjc 

; point back to the old DP 

; and put the return address back 

; restore old DBft 



end 

rt* ***********■■***.***•■• + •************ 



FindMaxWidtfi - this routine finds out how wide tha window 
should be Tor the currently installed lent. 



«*ll**l************t*.*»*l**» ******* ************* 



************* 



rlndHaxHldth start 

using WindowData 
using FontData 
using GIobalDati 

Push Word ID 
_G«t Font Flags 

Ldy (oFlag- 
Ida (0], y 
Lsr a 

and tSOOQl 
pha 

_SetFontFlags 

at! Max£cFar 
Ida fl 

sta Llneccunter 
Llr.ELc-op anop 

* 

PushWord tD 

phX 

phk 

pi a 

and #SQ0FF 

pha 

Ida LlneCountef 

asl a 

tax 

Ida MneTable,* 

pha 

_StringWldth 



; save pretf set mono /pro flag 



; keep the result on the stick while 

; we set it to what we want (as 

; defined by its window type set up 

; when we open this window) 



; space for width result. 

? Get a pointer to the current line, 

; The upper word is the sane as the 

; pr.--;r.iT bank.. 



; The lower word is stored in a table. 
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LessThan 



Li Recount er 
KanSoFar 



pla 

cmp MaxSoFar 

bee LessThan 
Sta MaxSoFar 

a nop 

inc LineCoynter 
r.;, lineCounter 
cmp tWumLinos 
bec LlneLnop 

Ida MaxSoFar 
cle 

adc (ID 

sta DataWidth 

SetFontFlags 

rta 
da 2 
da 2 
end 



; How does this line coirpare with the 

; previous longest Una? 

; > or -, so save It as record holder. 

,■ bi^mp current line 



,' Get the width of longest line. 

,* Add In room for left and right margins 



; restore eld settings 



* DoClcselteffl 

■ Close a window, and dispose □: 

' and remove It from window list. 

* menu and disallow printing;. 



extra data fin WreiCont 

K no windows, then dim "Window" 



DoCloselteiri 



Gotrt 



Therelsona 



START 

using GlobalDATA 

p-ushlong 10 

_Froncwindow 

pla 

sta whtchwlndow 

pla 

sta whichwtndow+2 

ora Whlebwlndow 

bne There! some 

mle 

PushLong WhichWlndow 
_ClD3eNC-A3yWlnPr r 
bec (Sot It 



; Must be one of mine, 
dot heels PUSHLONG to 

PUSHLONG whSchwindow 
GecWreiCon 



pla 




sta 


temp2Ha.rtdle 


plx 




stx 


Temp2Handle'2 


j« 


de-re I 


sta 





stx 


7 


Idv 


(oftendle 


Ida 


[0J,y 


sta 


FlcHandle 


: ry 




iny 





-It 'a the front window we're deleting 
,-...so get its GrafPortPtr 



; get result for pushing in a sec, 

f was there one? 

; quit now 

; if it la a system window, this win 

,* close it 

; no error so done 



; space for resalt 

;refcon has handle to data 

fthe refcon to de-allocate 
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ttOIle 



Ida [0],y 

sta PicHandle+2 

ldy loFlag 
Ida [01. y 
beq lcsaplc 
stz FicHandle 
etz PieHandle+2 



jar Arijwlnd 

elc 

ade I 100 

sta IDdelete 

l<Ja windex 

cir.p (1 

bns MoreThanGne 

pushlonij loriglteir. 

pushword fO 

pushword (HindcwsHenulD 

_InsertMItem 

?'js.1»ord t $00(10 
PushWord IWir.dnwsMenurD 
_SetManuFlag 





Ida 


(True 




Sta 


NaedToUpdata 




ati 


ErintAvali 




: da 


120 




sta 


WxOffset 




Ida 


H2 




sua 


wyoffset 


HoreTharvOne 


Ida 
pha 


IDdelete 




_DeleteHItem 




dec 


wlndex 




Ida 


"Index. 




beq 


nomcie 




at a 


IdCounter 




Ida 


♦ 300 




sta 


IDstart 




S-.H 


ICNew 


bank 


:oa 


IdStart 




CTC£> 


IdDeleta 




boa 


DMt 




ir.e 


Idstart 




bra 


back 


Dolt 


pushword IdNew 




pushword TdStart 




SetHltetnld 




Inc 


idStart 




inc 


IdNew 




dec 


IdCounter 




bne 


back 


NcMore 


Ida 


IC 




pha 





; the plchandle (we'll de-allooatej 

; check If picture or font 

; Hag so we don't dispose 

f goes and pulls window from Window List 

; position returned in a-retj. 

f start at 30D 

; the MenuIQ to de-allocate 

,' If only one, We must be special 

; We're now deleting the only window 

; left. 

; add old "no windows'* menu Item. 

,'Disarilfl windows menu 



; Disallow printing 

j reset start loc for window sizing 



; now delete this item from menus 



■now, renumber list 

; none left, skip 

; counts how many 

,- always the starting no. 

; will be first 

f and the new one 

; is it the one we delated? 

l nope, go. re-set ID 

,- yes, skip over it 



7 re- calc size 
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pha 

PusbWord IWlndowsMenuID 

_CalcMienuElze 

Pushlgng -expSHandle 
_D 1 apcseHa ndl e 



,*qet rid of re f con area 
;is it rant 

;<jet rid o£ picture area 
;get rid of wlndo* 



Ida FicHandle 
fcw.e dodisp 
Ida PIcHandlo+2 
beq skipdisp 

DnDisp Pushlcng PicHandle 

_DisposeHandle 

s*lpDisp PushLong Whlehwintk™ 

jcloseWindoH 

ski P rt« 

""■■Hiuim..!!,,,,,,,,,, 

* 

^ rfbicnwindow" and returns in a- M g. where it -a position was 
• M0t«: it's optimised to find things near end of list 

hr/E™ ^"^ ??" ° ther End ' ¥ou ' d need B ™« different logic, 

this ":r 5 " ] ^ ¥OU ' U OPEn ' l0 <* at 1^ and close it, so 
this method! seems bast) 



AdjWind 



adjloop 



Shoirelt 



Sbc-vecblt 
AdJOqna 



IdNaw 

Ids tart 

Idcoimter 

IDdelete 



Ida w:.-,dfx 

tay 

dec a 

a si a 

asl a 

Hta. iDCounter 

day 

bml AdjDone 

tya 

asl a 

asl a 

tax 

Ida WlndowLlst.x 

cr.p Whichwlndov) 

bne ad j loop 

Ida WindowUst+2,x 

cmp WhichWlndon+2. 

beq shovechfc 

bra Adjloop 

Ida WindowList+4, jt 
Ma wlndowlist,* 

Ida Windo«fLi£t*6, x 

at a WindowLlstt2,jc 

inx 

inx 

inx 

inx 

cpx idCounter 

bne shoveifc 

tya 

rt3 

ds a 

ds 2 

da 2 
ds 2 
END 



;use tbla to count thru 

f pt. before last for end (a-2)*4 



rg«t the pointer (uniqueness exists; 



;now shove things up 
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rit. kkkkk-mkwk kmmmk k >. »* ** F fr*444» * * ■ * kk kmk k kkkkkwkk k k k k k k k k k * k * ■* * 
r 

•Paint 

* 

* This draws picture In the window when task master calls. 
> 

kkktkkkkkkkkk.kkkk. + -kk.k.k.k-kkkkkkkk + kkmkkkkkk-k + *kkkk*.kkkkkkk*-k + *kk-kk 

taint START 

using GlobalData 



• get my own zero page 



phb 
phk 
p.ta 
phd 

Ida MyZP 
ted 



git the correct window port {gat here from within taskmaster) 



■ ■ ■ * * * ■ * - 



push long 10 

_GetPort 

plx 

ply 

P05HLONG ID 

phy 

phx 

_GetWrofCon 

pla 

eta Tesnphandle 

pin 

stH TempHandle+2 

jsr Deref 
Stfl 
StK 2 



;get result for pushing in a sec. 

; space tor result 

; saved the port here 
,-refeon has handle to data 



; dereference 



Idy (o Handle 
Ida [0],y 
sta plcptr 
pha 

ir.y 

iny 

Ida [0],y 

sta pleptr+2 

tax 

pla 

}sl Paint It 

Ida TempHandle 
Ids TempKandla+2 
jar Unlock 

pld 

plb 

rL! 
END 



; gat handle to pic data 
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* Paint It 

* The routinev which actually does the painting when passed the 

* the handle to the picture in the a C x registers. 
* 

*lr.Hlii.i,HliittH*MMM#**»it*t*IMll**^#l*tttH*tlitHHIfl 

PaiMIt START 

using GlobalData 



Pshmor 



phx 
pha 


; save 


jsr daref 
sta plcptr 
stx plcptr+2 


f daref 


PusrtLong iSrcLosljjfo 
BuahXong (SrcRect 
P'jshWord K 
PushWord #0 
PushWord *0 
_PPToPart 


■ K 

; y 
; copy 


pi s 
Pi* 

jsr Unlock 




rtl 




END 





* DoGaAway — not necessary because wa handle it the same aa 

* Doc lose It em. 

Mn*.ti.M*Himtnm 1 iii i i,n.„,, 11 „„ t „ 1( , 11111 , ittHlt( 



DoWindnw 

Selects and shows window In response to menu selection, 

DoHlndow START 

using ElohalDATA 

PUSIflflNG HHICHHINDOW ; select rlrst so It only i^edraws 

JSelectWindow ; ones 

PUSHLONC WHICHWIW20W 
showwindc-u 

rt» 
END 
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D1AL0G.ASM (dialog boxes) 



* ft 

HOdgeEOdge: An eKafiple Apple IICS Desktop application. * 



Copyright (c) 19B6-B1 by Apple Computer, Inc. 
hi I Rights Reserved 



* A5ME5B1G Code file "DIALOG. ASM" — Various dialogs taking modal control * 



****■■■»»•• >*»**»Hf*'«H*»'«^«MM.t«*r'Mt»«*"IM»ll»«f^»l*«l 



1 ManyWindDlalog — Warning that too many nindows are open. 



(tanyWiKdClalcg START 

using GlobaiData 



Our Alert 



Iter! 



iteir,2 



pbj 


L 




push long (OurAlert 


pushlong f SO000 


CautlonAlert 


pli 


I 




Ct( 






do 


1' 


10, 125,80,520 ■ 


dc 


i ' 


2374* 


Be 


h 1 


SO" 


dc 


h' 


JO' 


uc 


;r 


10' 


do 


h 1 


JO' 


dc 


14 


I tool' 


dc 


LI 


ltan2' 


dc 


14 


0000' 


dr 


LJ 


1" 


dc 


12 


25,320,00,00' 


dc 


12 


Buttonltem' 


dc 


n 


Butl" 


dr. 


12 


00' 


dc 


U 


0' 


dc 


LI 


8" 


dc 


u 


1348' 


dc 


u 


'11,72, 200, 6W 


dc 


L2 


StatTexttSaOOO 


dc 


14 


Hag' 


dr 


12 


00' 


dc 


Li 


u- 


do 


'.■1 


n- 



get the Item hit 



bounds rect 

Id 



Id 

bounds rect for buttnr, 

type 

item de s crept oi 

Item ualje 

Item flag 

Item color 

Id 

bounds rect for message 
type + disabled 

item descreptor 
Item value 
Item flag 
Item color 



Sutl 
Usq 



str 'DK' 

str 'No more windows, please.' 



2nd 
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**#* ********** 



* DoJUrautltem 



*«•****»*#**.«.****,«„**.*, •«•* ***•«..»*„ 



Brings up about box and waits antll button prsss until 

It puts it away. Si,™* how te bulld , dialoq vin ^ by hsnd _ 

"*"**"■ "***" • — *,* ,„ 



DoAboutltem 



f 

ok 



Copy 640 

FixDBox 

JoinRect 



START 

using globalEata 

Pushiong #D 
PushLong «34'16-s 
PushWord My Id 
PushWord »D 
Pushlong Ifl 
JtawHandle 
pis 

bcc ok 
Ida #S81 
ldx 11 

]mp CheckDisitErrar 



a nop 

eta Appleieo-nH 

stx AppIeiconH+2 

]«t deref 

flta 
stx 2 

ldy 10 

Ida AppleIeon64Q,y 

ata [0J,y 

Iny 

iny 

cpy *34*l£+a 

tme CqpyfiflD 

ldx tSJO-lBO 

Ida ( 320+1 BO 

stx DRsct+2 
sta Dftect+6 

PushLong to 
Pushleng IDRect 
PusnWord (True 
PuehLong (0 
_NEwModalDiaiog 

Pla 

*ta MDialogptr 

pi a 

ata MDialooPtr+2 

Pushlong MDialogPtt- 
PushWord *1 
Pushlong tfluctonRect 
PushWord (Buttonltem 
PughLong lauttonText 



.' get. space for Icon 

,- IHnes ■ bytes/ line * rect 

; don't care where it goes 



out of memory 

Go and tell user error message, 

and use its UTS to exit from h erB . 



;move Icon to new space 



output 

visible 
re f con 
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PushWord <Q 
PushWord #0 
PushLong tO 
_NewDIt8si 

FushLgng MDlalogPtr 
PUShWnrd #2 

PushLo-ng tAppl el con Fleet 
PushWoTd HcoaItern*ItemDisable 
PushLong AppLeleonK 
PushKcrd to 
PushWa^d *0 
PushLong #0 
NewDILem 



Pushlong MDiaiogPtr 
PushWord 14 
PUShlong (TeJttRect 
PushWord tLorugstaCTeitii2+ltemDLsable 
PushLohg IStartOtText 
PushWord lEndOfText-startQfTeKt 
PushWojrd (0 
Push Long 10 
NMDItM 



3oMcdil PushWord ID 

PushLong »0 
_ModalDialog 
pli 

FushLnng MDialmjPtr 
C_oseUialog 

Push.Long ApplelcorJH 
JD1 EposeHandle 



,■ result 

; t\q fllterproc 

; chuck the item hit 



EReet 

ApjIsIconH 
Applel connect 

Apple : cor. 6 M 



rts 

dc i'2a,ia,i$2,iz9-io' 

ds 4 

dc 1" 135, 2D, 0,0' 

mop 

dc 1 '0,0, 34, 6-4' 
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TojttBect 
Start UtTojit 






DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 



do 

I i:5S SSSSSS! ==SK : 
E : S5B5B55BE3SB: 
" .-KSSSSKSSSSBS: 

h ■ ofof ffffff rrFFFF Bff e BeSF F F F^" FQ . 

b OFQFFFFFFFFFf .TF.fl.BF ^FFFF^FOFO 
h QFDFF FF FF 8a8BFPFB8Fr( , 9 ^FFFOFO 

h : D™FFF Sa8 a B B SBeSaB8BBBa86Be ™, 
h- nrOFK ^"""^'"^^FFFFOFa ■ 

h.^^ eeeoeeeeeeee eeFFFFFFDFn. 

?. ™ 6 * 6666fi6666 «66E66SFFFFFFOFn ' 

E »™ r "^"" 4 «*"*««4lFFFFDra. 

a CF yFFF5i5555 55 S555SS55i55i . 

h n°™f " FF11111 a ^" pK- 
h 0FOFFFPFFF1 ] llFrFFFlUlFFFFFFOFO - 

OrOFFFFFFFFFITfr. E - c .r.^„„:': frrt,FD 



ESpKHSSS 

: P°=S™ : 



center 
Out Line 



dc 15-4, 10, 135,340' 

a nop 

dc h'Oa^c'J',!'!' 

dc h'Ol'.c'S'.l'SOODB' 

dc e ' H « d 9ePodge',h-DD' 
dc h-(H., c . s . fl .^ 00 

£ ^ W^ri of routlnes ^*f" 



dc )i 
dc c 
dc h 

dc h< 



«*■ Apple ri0s develDpaHlnt teaffi laclljaltiot( 



dc Of., 
dc c > £ . 
dc h'QD 

dc c'D 



BerrsE, a. 

21 ass, ■ 



. Hit chens, 
°-G c'p. HcDonald, 
dc h'OD 1 
dc c'B. Harks, d. 



Cabral, c. Buy, ■ 
8- Kofiing, 5. ie e 



K. Rollin. 



Oliver, g. Oz-tlj., 



EndOfrext 



dc c'and 

dc h-DD 1 
dt h'OD' 

dc ssEv *** ^^, &>=. 

dc h'OD' 

dc CiSysDato- 
a nop 
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hetOnBect dc 1" 153, 205, a, 0" 

Battotslejtt str *OK" 

HUalogPtr ds 4 

END 

ft 4 1 ft ft * ft * ft * ■ *••***•***■>***** -It- * -ft i « s ft -ft ft ft ft ft * # * * ft ** * ***** * ft ft * ft # A 



* ShmPleaseWait / HideFleaseWAit 

' Brings up a nilndtni and immediately puts message In it 
■ (without waiting for update event} , 



****** ***i *» 



ltllUl>H«lM«tlt*Hii*IH MHil^M*il([«»Ml 



Shawieasewait START 

using globalData 

PushLong #0 
GetPort 



; save the currant port 



pi a 

st a save Port 

pi a 

Eta SavePort+2 

Eushtong *0 

FushLong IDliloglaffiplate 

_GetNBHMedalDlal(jg 

pla 

sta MagWinPtr 

pla 

sta MsgWlnPtr+2 

PushLong MsgWlnptr 
_Beginupdate 

PuahLeng MsgWinJtr 
__Dra«Dialog 

PushLong MsgWlnFtr 
_£nd'Jpdate 



; begin the updating process 



HideFleaseWait ENTHY 





FusfoLong MsgWinPtr 
_CloaaDialog 


; hide the alndau 




PusALang SavePort 
_SetPort 


; restore the port 




rte 




KsgWlnptir 


da 4 




DlalogTsmplate 


anop 

dc 1-30, 1 20,80,520" 

dc l'Trua" 

dc H'0' 

dc H'iteml' 

dp ia'DDOO 1 


; bounding box 
; visible 
; refcan 
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It anil ancp 

dc 12-134S 1 ; id 

dc 12' 19, 70,200, 640" .■ bounds rec± COZ text 

dc 12'StatText' ; type 

dc 14'Ptsg 1 ; Item desereptor 

dc 12" DO 1 ; Item value 

dc 1.2' 0" ; item flag 

dc 14*0' ," item color 
Msg str 'Please wait while we net things up, ■ 

END 



******* ************************* ***** A*************** *********** 
ll 

« MountBootDlsk; 

■ 

* Tlila la a routine that Is called whenever the application 

* needs to get something aLi the hoot volume and the 
" boot volume Is not on line, 

* 

' This can occur when loading fonts, tools or drivers,. 
«*************************#* A*********************** ************ 

HountBootDisls START 

^SetPrefix SetPrafixParams 
Get Prefix BetPreflxParams 





P'jshWord tQ 


;Space for resulL 




PushWard *\1A 


;x pes 




PushWord *30 


;y poa 




PushLong fPrcor.ptSt r 


(Prompt string 




PushLeng tvolstr 


j Vol string 




PushLong tOKStr 






PushLong fCancelStr 






_T LMouut Vol ume 






pla 






rts 




ErosnptStr 


str 'Please insert the 


disk 1 


OKEtr 


str *OK' 




cancel str 


str "Shutdown" 





GetPrafixParams dc i'7' 

dc ifVolstr 1 



SEtPrelixEarajnB dc i'V 

dc H'&aotStr' 



Vol str ds Ifi 

aootstr str ■*/' 



END 
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»tlM«1iMM»»»tt * * ****** ft ******** 11 *■**********# ft***********-*** 
# 

* ChecliTeolError 

• 

■ Cause system death If A register Is nonzero and carry set; 

* otherwise, it Just returns, 
* 

* Error code to make part of string, ia in A register. 

* ■Where" number to mafce parr al string is In X register. 
* 

********** *******mb* ft* feftftftfttftftftftftftftftftftftftftftft** ****** **■■******«** 



;II a tool error didn't happen 
;th<sn just return 

fBava error cede for now 

; Convert the "Where" debug trace 

;min±ier to a four-digit ASCII he* 
/string. 



ChicMoolEri 


or START 




bes HealCeaLh 




rts 


tttlDaith 


pha 




pea 




pea 




phu 




Hex it 




pla 




ata codes 




pi a 




sta codes*-? 



DeaLhHsq 

StartMag 
Codes 

LndKsg 



pla 

pha 

PuflhJjang tDeathMsg 

_5ysFaUHgr 



.■Restore error code 

;Exlt to system failure handler 
; (bouncing apple) 



■nop 

dc H'EndMsg-StartMsg' 

de c" At 5' 

■is 4 

dc c' ,- Could not handle error S* 

anop 

END 



****** **WR*ft**ft ft* ftft**ft ***************** 



*********** ******* ****** 



CheeltDlsltErrQr — Display stop alert dialog If ProDOS error happened. 
We sniff the A register to see If an error occurred, 
and assume the X register to be loaded with a 
"where" value, used to locate bugs. 



ftft-ftft* ft ft • ft m ft ft * ft ft ft* ft * * * + * ft ■ * * * * * 



ft* * *ft*ft* 



******** ***«■* ****** 



ChecliDlsJtError START 

using Globa IData 

phx 
pha 

_InltCursor 

pla 
pha 

Pushtong lOurErrstr 
PuahWord 14 
lot 2 Hex 



; Save the Where value 

; Save the error number 

; Set pointer—looks better than watch 

; Restore the error number 

; Convert the error message 

,* to an ASCII string 4 chars long 
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pla 

pha 

PuafrLong iqurwherestr 
?'jshwerd 12 
Intiffex 



Do this just for clarity (note that 
Where value is already on stack:) 
convert the Where value 

to an ASCII string 2 chars Lang 



pha 

push-Long tOurAlert 

pushlong ISOflDD 

_stopALert 

pla 

sec 

rts 



space for result 

Pointer to template 

standard filter procedure 

Draw box and wait for mouse OK press 

Get the item hit (the OK button) 

Set the error flag 
Return to caller 



OurAlert dc 1 '3D, 120, B0,52D" 
dc i'6666' 
dc h'BD' 
dc h'SO' 

dc h-ao- 

de h"9D' 

dc lfl'OKButten' 

dc 1-J 'Message' 

dc K'oooo' 



bounds rect 
id 



OKButton 



Message 

ErrMsgPtr 



dc i2'l' 

de i2'25, 320,00,00' 

dc 12'ButtonItem' 

dc M'OKHame* 

dc 12 '00' 

dc 12' 0* 

dc H'O* 

dc 12'134B" 

dc lZ'li.Tz^flO.ei^ 1 

dc iZ'StatText+SBDDy' 

dc 14'Msg' 

do 12' 00" 

do 12'S' 

dc i4'Q' 



id 

bounds rect for button 

type 

item des crept or 

Item value 

item flag 

item color 

id 

bounds, rect for static text 

typE + disable flag 

item das crept or 

item value 

item flag 

item color 



□Kuans 



str 'OR' 



Mag 
StartHsg 

DuxErrStr 

OurWhereStr 



inuMsy 



dc 11'EndMfifj-StartMsg' 

dc c'Diak error S' 
ds 4 

dc C occurrEd at S' 
ds 2 

dc c , ■ 

dc h'uD" 
a nop 



END 
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FONT.ASM (fonts) 



HlttTtklili^M *************** *»****»*A**r****l I ■ ■ * * * * * * * H ■ |l i a f * * * ft ******** A 

Hodgepodge: ftn example Apple IIGS Desktop application * 

* 

Cgpyright (cl 1986-87 by Apple Computer, Inc. + 

All nights Reserved * 



ASH65816 Code ItJe "FONT.ASM" — Choose font,- display font window contents • 



*»****»* a***********************-*-********* ********************* 

■ FdntData 
■ 

■ ■ * a ■ * * * * * * * * * * * *********** * ************************ * * * ******** « 
font DM* DATA 

fontvrinEtr ds 4 

DesiiedFont do iA "SOBOQFFFE" ,• System Font slie 8 

McmoFlsg dc iZ*Q< ,. start cut showing proportional 

curFDjitlnfo a nop 

CFflscent ds 2 

CFDescent ds 2 

CFMaxtjld ds 2 

CFLeadlng ds 2 



CurHeight ds 2 

LlneCountor ds 2 

CurPos ds 4 



Mudines ec-u 13 

LlneTable dc i'LinoO,llnel, Line!, Llne3,Llne4 " 

dc 1 ■ LineS, Llne6, Line"?, LineB, Llne9" 
dc i'LinelO^lnell.LlnelS.LlnelZfUnell' 

Lined ds 30 ; max. name len is 25 + 1 for length 

i ; and 4 for slie info 

LLnel str ■ ' 

Linei str 'The quick broun fox jumped over the laiy dog.' 

LineJ str 'She sells sea shells down by the sea shore." 

Line4 str " 

Lln#5 do h'ZO 1 
dc h'DO 01 02 03 04 flj ne Q7 08 09 0A 03 DC DD 0E OF' 
dc h'10 11 U 13 14 IS 16 17 IB 19 1A IB 1C ID IE IF- 
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LineS dc h'20* 

dc h"2D 21 22 23 24 25 26 27 2fl 29 2fl 2B 2C 2D Z£ 2F" 
<te h'30 31 32 33 34 35 36 37 3 B 39 3A 3B 3C 3D 3E tf. 

L.ine7 dc h'20 1 

dc HMD 41 42 43 44 45 4S 47 4B 45 4* 4B 4C 4D 4E 4F- 
dc h'50 51 52 53 54 55 56 57 5B 59 5A 5B SC 5D 5E 5F- 
LlneB de h'20 1 

dc h-BD 61 6? 63 £4 65 SB 67 6a 69 6 h 6 B 6C 6D 6E SF' 
dc h'73 71 72 73 74 75 76 77 7B 7 9 7A 7B 7C 7 D 7£ 7F' 
LIneS dc h'2Q> 

dc h'BO Bl 82 83 B4 85 86 B7 88 B9 9a BS BC BD 8E 8*" 
dc h'9 u 91 92 93 94 95 94 97 9B 99- 9A 9B 9C 9D 9E 9F- 
LlnelD dc b'2Q ' 

dc h-AD Al A2 A3 A4 AS A6 A7 A8 A9 AA AB AC AD AE AF' 
dc h'Bv fll BZ B 3 B4 BS B6 fl7 B9 B9 BA &B BC BD BE BE" 
Llnell de h"20' 

dc h-CO CI C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF< 
dc h'M Dl D2 D3 D4 D5 D6 D7 E8 P9 DA DB DC BD DE OF- 
Llr„ttl2 dc h'20 ' 

dc h'EO Ei E2 E3 E4 £5 E6 £7 EB E9 EA EB EC ED EE EF' 
dc h-FO Fl F2 F3 F4 FS F6 F7 FS F9 FA Fa FC FD FE FF- 



DoChooseFor.t 



DoChooaeFont START 

using GlobalDATA 
using FontDATA 

Pushlong la 
_GetPort 

PusiiLong tTempPort 
_Oper.Port 

PushLong to , „„„_ , 

«. t. I spice for result 

PushLong Desired/Font 

Push'Word 10 

_Ch<30seForic 

Ida :, B 
ora 3,s 

bne ItChanged 

pl g » chonseFont returned a OGDo, so the 

^ ; font hasn't changed 

PushLong tTenpPort 

_ClosePort. 

^SetPort 

sec . K 

r oad return 
rts 



ItChanged a nop 
pla 



sta DesijredFone 

Pla 

sta DesiredFont+2 

F US hWa«, DesiredFont ' ^ ^ feSUlt 
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Fushlong IH_Fname 

_GetFa."iitnfis 

pla 

Ida DesiredFont+3 
and ($DDFF 
pha 

Ids * A R_FPiame 
pha 

Ida R FHame 
and t SO OFF 
Luc a 

adc »fV_FName 
pha 

PushWord i-: 
PushWord 10 
IntJDee 



i Ignore result 

,• get font size in a reg 

; high ward of point &r to name 



; low vord of pointer 
; output length. 
," not signed 



Ida R_FN»mB 
inc a 
Ine a 
Inc a 
inc a 
eta H_FName 

Push-Long ITempPort 
_ClcjseEort 

Set Port 



f hump the length 



elc 
rts 

tmpeort d* 5AA 

BUG 



•good return 



f sire of graph port 



• SJispFontWlndow 



cispFDntMindow START 

using Font DAT A 
using GlobalData 



get my own zero page 



phb 
ph): 
pUJ 

phd 

Ida MyZP 

ted 



• get the correct window port Igot here from within taskmaster) 



FONT.ASM (fonts) 
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pusMong to 
JJet Port 
plx 
ply 

PU5HLCNG »D 

phy 

ptB 

j3etWHefCon 

pi a 

sta Teaiphandle 

plx 

stx TernpHanaLetz 

jar Defer 
sta o 
s:t 2 

ldy loFontlDt? 

Ida [0),y 

tax 

day 

day 

id* [01, y 

jal ShowFont 

Ida TerapHandla 
ldx TempHandle+Z 
jsr Unlock 

pld 
pit. 

rtl 

END 



j get resuLt for pushing in a sec. 

; space for result 

,■ saved the port here 



? de re 1 era nee 



,■ get che font ID 



ShowFont 



• Common routine to actually draw the contents of the window 

m the A [ x registers. 



agisters, 

""......IHHil,,,,,,,,,,,,, 

shoiffont START 

using GlohslData 
using Font Data 

ptui 
pha 

ph« 
pha 

PushWord 10 
_lnstallFotit 

PuahLcng *Currontlnfo 
_GetFontInfo 

■tl LineCounter 

ele 

Ida CFAseent 



UiktlMlitMltti... 



****•**-»** m» 



f save copy an stack 
; Install the font 

f Got Its size info 

; iero the line counter 

' calculate the line separation 
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adc CFDescent 
ade CFleadlng 
sta- curHelght 

FuahWord It) 
Pus Word #0 
_MoveTo 

pin 

pushword to 

phx 

FushLong tLlr.eQ 

_GetFamInfo 

pla 

pla 

Xba 

and # SO OFF 

pha 

Ida **LlneO 

pha 

Ida LineD 

and ISO OF; 

Lne a 

adc »U,neS 

phi 

PushWord M 

PushWord 10 

_Int.2Dee 

Ida LineO 
tnc a 
inc a 
inc a 
Inc a 
it a LineO 

PushWord (0 
_GetFont Flags 

Idy toFlag 
Ida [OJ F y 

:sr a 

and tSOODl 

pha 
_5.etFont Flags 



Llnelscp ar.ep 



Push-Long tCurPes 
_GetPen 

PuahWord 1 = 
Ida CurPos 
clc 

adc Cur Height 
pha 

Ida LineCounter 

asl a 

nan 

pb* 

phi 

Ida 1 r s 
and »?00FF 

ata 1,6 



; start tne pen position at 0,Q 



i get font id off stack 

; space for result 

: family number was in * 



; ignore result 

; high word of font Id 
? size in high byte 



; high word of pointer to name 



7 low word of pointer 

; output length 
; not signed 



; bump the length 



save prev set mono /pro flag 



keep the result on the stack while 
we set It to what we want (as 
defined by its window type set up 
when we opened this window) 



; get the current position 

; reset x position 

,* and y position 

; draw current line 
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Ids LineTable,x 

ptu 

_DrawStrine 

inc LlneCounter 
Ida Line Counter 
mp INunLLlnes 
bee LineLoDp 

_SetFontFliga 

rtl 

END 

t *** ******** ft ***** « ti 



; bump current lir.e 



; restore from saved position 



'** + »*** ■******■ n * t * i utAittut * * * 



doSetMono 



* *************** **<*i 



********* ******* * * * * * 



<>i>iii>iii>i H ,,„ 



doSetMono START 

using Font Data 
using MemiData 

Ids KonoFlag 

epr t$S2 

at a MonnFlag 

beq ChangeToMona 
PushLonq (PropStr 
bra SushlD 
Change ToMano Pus Hong IMonosti: 
PushID PushWord tMonoID 

SetMItem 
rta 



,-Cbange message to show effect In 
.-NEXT selection of this menu ltex, 
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PRINT.ASM (printing) 



* 

Hodgepodge: An exjF.pl e Apple IISS Desktop application * 



Copyright (c) 19S6-B7 by Apple Computer, Inc. 
All Rights Reserved 



ABH65S1S code file -PRINT. ASK- — Print dialogs; Print Manager calls 

It,****-*********** ****** ***** *** ****** ** « * fell I ■ * 1* a************************** 



******************•***********■*-■*<***■■**■*'*'**■*********'********* 



■ DoChoosErltem 



* This la the routine that handles the Choose Printer 

* manu item. 



DoChooserlteni START 

using Gl aba ID at a 

PushWord 10 

_PrChooser 

pia 

rts 

END 



****** ■ a ■ * ************* ***************************************** 

■ 

* BoSetupItem 

* 

* This Is the routine that handles the page setup Item. 

* 

I************************************************** *«********.***i 

DeSetLipltem START 

using GlobalData 



Ida Print Re cord 

ore Print Record*? 
bne AlreadyThere 

jsr Set upDe fault 

AlrsadyThere a nap 

Ipha 
pushxong. PrlntBecoi-d 
PrValidate 
pla 
Euehnord to 
Push long Print He cord 



PRINT.ASM (printing) 367 



jsrStJDialog 
pi a 

eta 

END 



* SetupCefault 

* 

SatupDefault STMT •**♦*.». 

Using GlobalDATA 

PushLong |n 
PushLong 1140 
Pushuord KylD 
PuahWord (SB01Q 
PushLong |Q 

_nowHandle 

pla 

■ta PrintBecord 

pla 

sta ETlntBaeard+2 

AlreadyThere anop 

PushLong PrlntRacord 
_prdefsult 



End 



* DoPrliitltam 

" Till ntnT tqUtlne " at handleS the prlnt ltm ln tte 



DcEfintltem SlMT 

using GlobalData 

pna 
pha 

_GatPort 

pha 

pha 

_FrontWindofcr 

pla 

sta WlndowToPrlnt 
pla 

sta wlndowToPrlnt*2 

or a HindowToPrint 

bus SomsthlngruPrlnt 
brl Skiplt 

ScmethingToPrlnt anop 

Ida PrintBecord 



get the current port 



; first see if there is a window 

; to print. 

; and eave pointer to it now 

,- before any dialogs are displayed) 
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A.reaiiySet 



eentlrmo 



Skip!: 



ora PrlntHe(:ord+2 
bne Alreadyset 

jar EetuFOefault 

a nop 
pha 

EusbLong PrintRecoro. 

_Prvalldate 

pla 

PuihWerd *0 
PushLong Print Record 
_PrJot01alog 
pi a 

bna continue 
brl skip It 

a nop 

_WalLCursar 

Fus^iLong tO 

PushLnng Print Record 

PushLong #0 

_PrCpenDoc 

pla 

sta PrlntPort 

pla 

Sta PrintPoi^L + 2 

PushLong PrintPnrt 
PushLong *0 
_PrOpenPagE 

jar DrauTopWlndow 

PushLong, PrintPort 
_PrelosePage 

PushLong PrincPort 
^PrClaaeCoG 

PushLong PrlntRecord 
PuehLong 10 
Push Long 10 
PrPicFile 

_InitCursOf 

a nop 

_SatPort 

rts 

END 



; space for result 

; ignore result since all is well now 



rasters original port 
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••tft«»«»****tit*1ilktl«»t*t«tt±*i^**fri1<tM«..^«4tfr*t>ti*t«t*li 



* DrawrapHLndow 



* * * * * * * * * * ft 4 * ft 4 * * C ******** tin******************** * * 1. 4 ■ » » i * A ft ft ft ft 

DrawTopWlndew START 

using GlobalDATA 
pha 
pha 

PushLeng Wlndc-wToPrlnt 
GetWHefCon 



J space far result of GBtWRefCon call 



pla 

Its TfheRefCan 

plx 

StM Th^RefCon+I 

jsr Deref 

st a 

stx 2 

ldy # of lag 

Ida [0],y 

beq LTsflPaint 



ldy ioFQncTD-»Z 
Ida [0J,y 
tax, 
dey 

dey 

ida [0],y 

jal ShowFcnt 

bra Ail Cone 



UseFalnt 



a nop 

ldy loHarrile+2 

ma [f>],y 
tax 
dey 
dey 

Ida [u],y 
jal Palntlt 



; get handle to pic data 



AUDone 



Ida ThoBBfCon 
ldx TheHefcontj 
jar Unlock 



rts 



theHefCon 



ds 4 



tdn.daWIoPrln.t ENTHY 
ds 4 



END 
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10. ASM (pictures and files) 



ltlllttTr«tt>Hll|*tt!li * * h J ■ K- * t. * * * . . , * ill A **-+* 



. ~ ...... , 



Hc-dgeFodge: An Example Apple IIGS Desktop application 



Copyright (c) 1936-B"? by Apple Computer, Inc. 
All Rights Reserved 



A5M6581& Coda file TO, ASM" — Picture Load and Save stuff cal". J .r.g ProDOS " 

* 



■ UiadOne 

t 

' Loads the picture whose path name is passed In 

r 

* NamaPtr 
■ 

* to address passed In 

FlcDectlN 



LcadQrca 



eontL 



srwtT 

using lOData 

_OPEN OpenFarams 
bcc centl 
Jmp E*mrl 

a nop 

Ida OpenID 
sea Read ID 
sta CloselD 



eonti 



_READ ReadParams 
bcc cent 2 
jmp Errorl 

a nop 

_Closa ClOssParanis 

clc 
its 
and 
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" SaVeOna 



* Save* Che picture whose path name Is passed in 

NamePtr 

* frorc address passed in 

* PieDestOUT 



SavoQne 



r<t««HtH(m*ii„ t llMiHHIIHiil*ttH|»H*miM 

START 

using lOData 

Ida Na.iiePtjr 
sta NitieC 
sta NameD 
Ida NamePtr+2 
sta NaraeC+Z 
Sta NineDt? 

_Destroy DestParams 



SuperHires pictura type 
standard type » D 



Ida I5el 

sta CType 
Ida 10 

sta CAux 

_Create ereateParms 
bee cento 
jtnp Errorl 

CunL " _Open CpenParams 

bcc contl 
Jmp Errorl 

-'-'-"■-"- anop 

Ida OpnnID 
sta WritelD 
Eta CiOselD 

_w&TTE WrlteParams 
bcc cofitz 
imp Errorl 

cant 2 a nop 

_Cloae ClossParama 

clc 
rts 

end 

*""***"*■*** »*•»***•••* «•******** .,*... ,.,,,., 

Errorl — handle disk error during .read or write 



Errorl 



START 

using lOData 

ptu 

JTlose CloseParams 

pi a 

jsr CheckDiskError 

rts 



END 
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GLOBALS.ASM (global data) 



* I 

Hodgepodge: An example Apple IIGS Desktop application * 



Copyright (c> 1986-87 by Apple Computer, Inc. 
All Rights Ha served 



* A5K65B16 Code Elle "GL0aM.5.ASM™ — Global variables and misc. routines 



■ ■»* ** * t * * * * * *« * «**«*« * * « * # ftftft 
• SlobalDATA 



M#» ft ft ft* ft ft ft* ft • ft ■ ft* I ft > » ft ft « ft ft ft « « 

GlobalData DATA 



iftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft 



Ift*ft**ft44**ft**ft*ftftftftftftft*ft*ftftftft*ftft* 



Trampt 


do il'19',e'Lead which 


Picture: ' 


Proopt2 


de ll'19',c'Save which 


Picture; ■ 


Huff set 


dc i'20' ; 


offset 


for upperleft window corner 


Wyoffset 


dc i'12' 


offset 


for upperleft window corner 


nullReot 


dc 1-0,0,0,0- 






reply 


anop 




;SF GET/BUT FILE record 


r good 


dc 12'0" 






r_typ» 


de 12 >u' 






rjnuityp 


dc i2'D' 






r_fname 


da is 






r_fullpr. 


ds 128 






0'Jlc Pa raits 


do 14 'Q 1 








dc 1 -54000' 




; am res'.arubie In memory 


,- ToolTaole 


dc l-ll' 






7 


dc i' 4, $0101' 




," quickdraw 


r 


dc 1" 5,30100' 




; desk manager 


; 


dc 1-6, $0100' 




; event itanager 


; 


dc 1'14,SD103- 




f window manager from disk] 


: 


do 1'I5, 30103' 




; menu manager from DisJt! 


■ 


dc 1' 16, S0103' 




; control manager form disk! 


■ 


dc 1 '20,80100' 




; linn edit 


; 


dc l'21 r S0100' 




; dialog manager front disk! 


; 


dc l'23,SO100' 




; standard files from disk! 


■ 


de 1-27, 50100' 




; Font Fanager 


; 


dc 1 "28,50000- 




,' List manager 


; ThlsModa 


dc I'SOOBO' 




;lnit mods; 640 


SrcLodnfo 


de i'SSO" 




;PPtoPort 640 panne 


?icPtr 


da 4 
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Event Re cord 
EuentWhat 
Event Mes sage 
F.ventHhen 
EventWhere 



dc i'lSD" 

dc I'D, 0,200,640' 

dc i'0, 0,200,840' 

anop 

ds 2 

ds 4 
ds 4 

is -1 



EventModlfiars da 2 



TasxDATA 
TaskMas* 



ds 4 

dc U'SQFFF' 



OuitFlag 

DlalogPtr 

« Index 

Last Wind 

MyZP 

; ZpHandle 

,* My ID 

Vlndex 

VEable 

WlndowLlxt 

WbichWlndow 

T«t.pHandl« 

Tesr.pJKandle 

FlcHandle 

Save Port 

SavcType 

ActivateFIag 

NeedTo Update 

ThisWType 

Lastwtype 

PrintAvail 

PrintHecord 
PrlntPort 



ds 2 
de 4 
da J 

gequ 15 

ds 2 
ds 4 
ds 2 



I* 
la 



2 

16*4 
ds 16*4 
da 4 

4 

' 

■'- 

■; 

1 

; 

: 

- 

1 

I'D' 



is 

1:. 
tl 

:s 
is 
ll 

: ; 
14 
:. ' 
etc 



da 4 
ds 4 



VolNotFound gequ 545 



,' Index, to next avail. window ID 
; Maximum number of windows open 



t Index used to list of what WAS visible 
;llst at what WAS via. when Hiding all 
;all windows handle go into this list 
;will contain window pointer, cut. window 
I some temp handles 

; handle to picture data 

;Save current port onv for ShowFlwait 

,■ f lag for checJc front window, 

fused to prevent multi menu redraws 



rMaite sure this starts as 

; handle to print record 

: pointer to printing GrafJort. 

; prodos error 



MyWlndowInfo 

This is the data structure used far the windows we 
allocate. 



MaxNaraeSize 


■ • ! . ,1 


□Handle 

oBlanx 

oLenqth 

oName 

oWStuff 

oFlag 

oExtra 


equ 

equ c-Handle+4 

equ oBlank+1 

oqu oLength+1 

aqu oJJamo+MaxNaireSl 

equ e*KStufft6 
equ oFlag+1 


aFontlD 

-■ 


equ oHar.dle 


KywinfoSiEe 


equ oE*tra+4 




END 
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largest name we allow 



; if the type la for font, 

; the first rield is a FontID 

,' rat nor than the handle to picture 

; data. 



Hodgepodge Source Code: Assembly Language 



• HDati 



IODiGi 



DATA 



CT&ateParms airap 



NameO dc 


I4'0' 


dc 


12-SQQC3' 


CTVjw dc 


12'SQ0Q6' 


C.V-x dc 


14' $00000000 


dc 


ii'SOOOl" 


dc 


12'SOtJOO" 


dc 


12 '$0000' 


BestPafams 


apinp 


HaneS 


dc 14 *Q' 


OprnParajr-s 


ancp 


OpenID 


da 2 


HmmPtr 


ds 4 




da 4 


PcadPatair.s 


a nop 


Readi; 


ds 2 


PicDestlN 


ss 4 




dc 14'SBOQD' 




da A 


5 Read? a raps 


a nop 


PReadTD 


ds 2 


PfteadLoc 


da 4 


fBflaflslie 


ds 4 




ds 4 


HarfcParams 


jfi'jp 


MarkID 


da 2 


CuxrantMark 


a nop 


Hark 


ds 4 


WriteFarams 


anop 


WrltelD 


ds 2 


PlcDestMJT 


ds 4 




dc 14-$SO00 1 




ds 4 


ClaaePa-raifi 


a nap 


Close ID 


ds 2 



DRNWR 

BIN 

Auk. 

type 

create date 

create time 



f this many bytes 
; haw many uTerEd 

; far reading a packed file 



; this many bytes 
; how many Ufa red 



; this tissny bytes 
; hovj many xferad 



END 
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* Ignore 

* Does not do a whole lot. 

•t'-IllltlHlHllltlllllllMltHtillltlllllllllitlltlKltHHIIII 

Ignore START 

rts 



■ 

• Derefs and lock* the handle passed in a,x. Result passed baen 

• In a,x. Trashes en zp. 

i 

• •****#*-*###%***#**** #****##*#* #***t**4 #*##+#*%*#*##### 14****4*4 
DerejE START 

sea Q 
sex 2 
ldy 14 
Ida [o),y 

era ISBODO 

at a 10] j y 

dey 

dey 

Ida 10] ,y 

tax 

Ida ;:j 

rts 

END 



* Unlock 

* trnlockg the handle passed in x and a. g li trashed on ib 

■ 

ii.timntnii*4ni*tii(iniimiii. 1 i.tiiimin.im.ilili»n 
Unlock START 

s-ta 

at* 2 

ldy 14 

Ida [0],y 

and (S7FFF 

at* [0],y 
rts 



. ES3 
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Appendix F 



HodgePodge Source 
Code: C 



HP.CC 373 
MENU.CC 382 
EVENT.CC 365 
WINDOW.CC 390 
DIALOG.CC 400 
FONT.CC 405 
PRINT.CC 409 
HP.H 411 
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HP.CC (main program) 



/****■***»■»«* +*» + ********■******-**«•»**»*** ************************ 

* KcdgePadge: An example Apple JIGS Desktop implication 

* Written by the Apple IIGS Development lean 
■ C Versionn 4.0 

Copyright (c) 19B6-H7 by Apple Computer, Inc. 

* All Rights Reserved 



This program and its derivatives are licensed only For 
use on Apple computers. 

Works based on this program must contain and 
conspicuously display this notice. 

This software is provided for your evaluation and to 
assist you in developing software for the Apple 11GS 
computer. 

this is not a distribution license. Distribution of 
this and other Apple software requires a separate 
license. Contact the Software Licensing Department of 
Apple Computer, Inc. for details, 

DISCLAIMER Of WARRANTY 

THE SOFTWARE IS PROVIDED -AS IS" WITHOUT 
WARRANTY OF ANY KIND, EITHER EXPRESS OB IMPLIED, 
WITH RESPECT TO ITS MERCHANTABILITY OR ITS FITNESS 
FOR ANT PARTICULAR PURPOSE. THE ENTIRE RISK AS TO 
THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH 
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU (AND 
NOT APPLE OR AN APPLE AUTHORIZED REPRESENTATIVE} 
ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, 
REPAIR OR CORRECTION. 

Apple does not warrant that the functlofia 
contained in the Software will meet your requirements 
or that the operation of the Software will be 
uninterrupted or error free or that defects in the 
Software will be corrected. 

SOME STATES DO NOT ALLOW THE EXCLUSION 
OF IMPLIED WARRANTIES, SO THE ABOVE EXCURSION MAY 
NOT APPLY TO YOU. THIS WARRANTY GIVES YOU SPECIFIC 
LEGAL RIGHTS AND YOU MAY ALSO HAVE OTHER RIGHTS 
WHICH VARY FROM STATE TO STATE. 



Source file HP.CC — 

********* i *«**fr**»»*****t* *** 

(include <types.h> 
Unclude <prodos.hj 
♦include <misctool,h> 
♦ include <qu.ickdraw.h> 



Startup and Shutdown routines 



■ . * »,*.*>.*F..t>.. 



' * A ********* / 
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(include <qdaux.li> 
(Include <windoH.h> 
(Include <Eieitiory .. hi 
(Include <dlalog.hs 
(Include «nenui,h> 
(Include <control,l!> 
(Include <desk.'n> 
(Include <avent.h:> 
(Include <llnaadit.h> 
(induce cr,lsctool,h> 
(include <locator.h:> 
(include <stdflle.h> 
(include <pflnt.h> 
(lncl'-de tfont.h? 
(Include <intmath.h> 
(include <llst .ln> 
(Include <s crap, hi 
(include "hp.h" 

tern Int _taolErr,* 

alaan Tools Found - FALSE, 

Ml Ok - FALSE, 

PManacjerFound - TRUE; 



/* Do we have tools 1 */ 

/* assume the PH is there •! 



1[ 


t MylD; 










il 


it TbisMade ■ 


DlBDj 






/* lnlt mode ■ 


it 


(t Tool Table 


[i - in 




{* 


Number of items */ 






i. 


ox:;:, 


," 


QuickDraw II •/ 






s, 


0x100, 


/■ 


Desk Manager */ 






s. 


Oxl DO, 


/• 


Event Manager V 






u. 


0x100, 


" 


Window Manager "/ 






15, 


0x100, 


i* 


Menu Manager */ 






16", 


0x100, 


.'• 


Control Manager */ 




IB, 


0x100, 


■'• 


QuickDraw Auxiliary 




19, 


0x000, 


!• 


Print Manager »/ 




20, 


0x100, 


■- 


Line Edit •/ 




21, 


0x100, 


/' 


Dialog Manager ■/ 




22, 


HxlOO, 


.'■' 


Scrap Manager ■/ 




23, 


0x100, 


/• 


standard File */ 




21, 


0x100, 


f* 


Font Manager ■/ 






26, 


OstOOO); 


f* 


List Manager */ 



cnar *'y,*2; 
CrjfPertPtr orlgPort; 

/* This is the routine that will do the Initialization °* tools, will ailocats 
ft mamory and all related [jess 

boolean StartUpTcols O 



static char SysToolsDirStr [! - "\pVSYSTEM/TQQLS n ? 

static FileRBC ParamBlocic - ( SysToolsDlrStr , NULL ],- 



TLStamup t) ,' 



/* for callinej tools */ 



HP.CC (main program) 
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ChockToolError [1) j 

MylD - MMStartOp () ; 

CheckTeolError 12',; 

MT£tartUp(); 
CheckTool Error (3) ; 

y - NewHandle (OxBGOL, 
MylD, 

attrBank + 
al_Lr?aqe t 
at tr Fixed + 
at tr Locked, 
OL) f 
ChEckTOol Error (1); 



/•ID for all transactions '/ 



/' Wise, Tools ■/ 

/* Make sure all Is OX 



/* Eleven pages 

/" put It to my name 



/■ don't care 



'y; 



/■ deref handle 



QDStartUp ((int) i,ThlsModfl,MAXSCAN,Hyn>) ,* 
CheckTool Error (5) ; 
OrlqPort - Get Port (),- 



EKStartUpI [intl z + 0x300, 20,0, 64D, a, 2B0,MyID) ; 
checkToolError (61; 



/" Event Manager V 



Movelo [20, 2d); 

SetBackColor (0) ,- 

SetForeColor (13)/ 

Drawstring ("\pOne Moment Please... ■); 

Showcursor (J; 



TryAgaln: 

CEr_FllE_lNFO (iPararoBloch) ; 
If (_toolErr) 

if (MnutitBTOtDIsJt — U 

goto Try Again; 
else 

return [false J; 



Loadrools [Tool Table) ; 
CheckTeolError (7) ; 

QDAuxstartupi (); 

CheckTeolError (8} ; 

Ha it Cursor Of 

windStartUp (MylD); 
CheckTool Error (9) ; 

RefreshDesktop (NULL! ; 

ctistartUp (MylD, (Int) i + 0x400); 
CheekTool Error (10) ,- 

LEStartup (MylD, (Int) z + 0x5001; 
CheckTonlError (11); 

DlalooStartUp (MylD); 
CheckToolError (12) ; 

MenuStarLUp (MylD, (Int) i + Px6Q0); 
ClreckToolError (13) ; 

Desk Startup (1 ; 
Chock Tool Error [14) ; 



/* Exit function unsuccessfully «/ 
f* Now it's ok to do this V 



/» Show wristwatch cursor */ 



t" All we nead Is inlt'ed now •/ 
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Stiff 



wEleasewait (),- 



SFStartUp (MylD, lint] z + 3x700); 
Check Tool Error (1.5); 
SFMlcaps (true] ; 

fMStsrtUp (bVID, (int} z + CxHOD) j 
ChackToolError {16) ; 



/* the watch cursor is up */ 
/* while we count the fonts */ 



List startup (); 
Check Tool Error (17) ,- 



/* >l< Note, not ListstartUp with upper case "U™[ */ 



ScrapStartUp (If 
CheckTool Error (IB) ; 

PHStartUp (MylD, (lntl % + 0x900] j 
CheckTool Error [19) ; 



HlfleFleaseWaU I) I 
I nit Cursor (I; 

return (true) ; 



/■ BEmove dialog box */ 

/• Show arrow cursor *l 

/* Exit function successfully */ 



ShutDownToola () 



DeskShutDown (),* 



if (WindStatus () I- 0) 
HideAllWlndows (J; 



Lilt Shut Down 1 




FMShutQown i 




Sc;ap3hutDown 1 




EHShutDown i 




SFShutDown ( 


1: 


HenuSnutDown I 


1 ; 


DlalegShutDown i 


■ * 


IiEShut&own p 


); 


CtlShutDown i 


) i 


WlndShutStwn i 


) p 


QDAux Shut Down i 


f * 


EMShutDown . 


r t 


QDShutDown ( 


i p" 


HTShutCfOwn < 


J ,■ 


if ftWStatus () 
1 

DlspoEeHandl 


1- 01 


e ty); 


MMShratDown 


(My IB! 



TLShutDown () ; 

1 

/• MMU program routine '/ 
Hijin (] 



if (StartUpTools (1) 

{ 

SetUpMemia (I; 

MainEvent <); 
) 
ShutDownTools () ; 



/* Try to Initialize tools 



/* Shutdown tools even if didn't run V 






HP.CC (main program) 
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MEN U.CC (menus) 

* Hodgepodge: Ah example Apple lies Desktop application 



Copyright (c) 1966-97 by Apple Computer, Inc. 
All Rights Reserved 



source file MENO.ec - Menu bar Inserting/deleting / vectoring 



(include <types.h> 

• Include <tnjenu.n> 
(include <desk.h> 

(include <window_h> 

(Include <3nemory.h> 

♦ Include eintmaeh.hs 

I Include <misctool.rs 

(include <texttool.h> 

(include "tip.h" 

f Bunch of routines defined somewhere olee */ 

extern Docig-seltemj) ; 

extern DoAboutltemO ; 

extern DoQultrtam() ,- 

extern Doqaenltejti () ; 

extern DoSavelteml) ; 

extern DoCfiooeerltem (J ,- 

cxt em De-Set Upl t em ( i ; 

extern DoprintItem(} ,- 

extern DoCJiangeHes [) ; 

extern DoOpenItem() ; 

extern DnSetMnno [>; 

extern DoShowVers (J ; 

extern WnTasxRec The Event,* 
extern Grafrortptr Wblchwlndgw; 
extern GrafPortPtr HindewLlst [16] ; 
extern int windex; 

char IDstrtS] - u \\H3QD\r"; 
extern char str[] ; 

f Here we have all defines for a n che ^^j. ., 

char 'Menus [J - [ 

/' Fonts menu »/ 

"» Font* \\m\t\ 

—Display Font .. .U*FfN:2 6(\r\ 

-Display Font as Kono-spacedU-MmN^r,-, /. ^piler adds -0- at the end v 

/* windows menu •/ 

"» Window \\mS\T\ 

"No Windows Allocated\\N2S9Vr.", 
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/' Edit Menu. V 

*» Edit \\DN3\r\ 

—\\X29W\T\ 
— Cdt\\*XxN251\r\ 
— CspyU*CcN252\r\ 
— Faste\\'VvN253\r\ 
— Clflar\\N2S4Ar.", 

/* Tile Menu */ 
"» File \\N2\r\ 
—open ...W»OoN25B\r\ 

-<lose\\M255\r\ 

— Sive As . . A\DH259\r\ 

— \\H2SBD\r\ 

-Chwse Printer.,, Utf260\r\ 

— Tija setup . ..\\DN261\r\ 

—Print . . .UD'PpN26Z\r\ 

— \\NZ5BD\r\ 

-Qult\\«QqNJ57\r.*, 

If Apple Menu */ 

*»aS\XNl\r\ 

— about Hodgepodge . . . \ \ M2 5 6\ r\ 

— UH2SBD.'); 



AddTaMenu(l 

I 

SitiRecPtr dereftemp,- 

DitsaecHanaie Temptfpndle; 
lnt index, 1; 

WnichWlndOhf - FrontWlndow [) ; 

TmpKandle - (DataRecHandlel GetWRef Con (WhichWirniow) J 

derEftemp - "rempHandle; 
RLoek ITempHandle} ; 

!nt2DactMindex,IDStr + 3, 2,0) ; 
IDStr[3] I- 0*3D; 
ID5tr{4] I- 0n3D; 

index - (detettemp -a Str[0]| + 1; 
tor (i-0;l <-6;i++) 
dereftejEft -> str[l + Index] - 10str[l); 



InsertHIteinii (dereftemp -> Blank) , Qxff£f,Windou£Meii.ulD} ; 

/* this Is the first window V 



II H(Kindex)) 
[ 
DeleteMItem (2 S9J ; 

SetMenuFlag (OxffTf, Window sMbnlHD) ,- 
DrawMenuBar () ; 
I 
CalhMenuS Lee (OL.WindotfsMenulD) ; 
HiiidnifLlst[Windeii] - HhlchWlndow,- 
KLndwcH-} 
HUnlock [TeinpHandle) ; 



f* Token item »/ 
/* highlight the menu 



DcMtemd 
I 



WhlchWindoH-wlndawLlst [ (TheEvent.wmraskDabasOxt It fj 

DeMlndowO; 

HillteKanu (FALSE, TneEvent.wmTaskData/Gx/rl'f) ; 



300 J; 






MEIMU.CC (menus) 
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DaMenufi 

I 



switch [TheEvB-nt.wnTaskData i Oxfffri 



case OndoID 
ease Cut ID 

cage Copylfl 
ease PastalD 
case ClearlD 
case ClosowiD 

case About ID 

case OaitID 

case OpenWIn 

case SavelD 

case Choose ID 

case SetUpID 

Case Print ID 

case ShowFontlD 

ease McnoID 

case 295 

default 



: break; 
: break; 
: break, - 
: break; 
: break ; 
: Doc lose I tern (|, - 

break; 
: DoAboutltem{j ■ 

break; 
: DoQuitltemO; 

break ; 
: DoopenltemO; 

break; 
: Do5aveItem((; 

break; 
: DoChooserltemO ; 

break; 
: DosetupitejisO : 

break; 
: PoPrlntltem in- 
break ; 
i DoCpenltepi () ; 

break; 

: DoSetMono ; 

break; 
: btEak; 

: .DoWTtemj); 



/* we do nothing with *( 



/* these ! 



HlliteMenu (FALSE, TheEvene .wmTaskDuta/Ditffff J; 



setUpMenus () 



; 



int Menulooper; 

SecKTitleStart (10) ; 



Set starting pes of menus 



t6t Stt&JTSTZi a™, «— h, 

HT^Tr ^^ » ;: *« *»■-, If any •/ 

DrawMenu&ar (^ L S* *™ ° f M ™ S '' 

I Dran the menu bar on the screen */ 
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EVENT.CC (main event loop) 



Hodgepodge: An example Apple IIGS Desktop application 



Copyright (cj 19B6-B7 by Apple Computer, Inc. 
AL1 Rights He served 



Source file EVENT. CC — Klin event loop and window activation 



include <types.h> 

lnci Ude ^memory . Ji^ 

include window. Tis 

Include <prodos.h> 

include <niLsctocil.h> 

lncl-jde <texttcal. h> 

lncl'jda <Snenu.h> 

Include "hp.h" 

enteni int _teolErr; 
extern PManagerFound,- 

int Quitrisg - Q; 
UrafPartPtr I-istWlndo* - NIL, 
ThisWindow - NIL; 

Int Activ*t«rlag; 

itiuct. HandleRec \ 

char *ptrpart; 
Int flags; 
I; 
/* tot Open 

typedef struct OpenHec | 
Hard openRefSi;r-i; 

?tr opa neat ft name ; 

Handlo iOBufter; 

) QpsnHee, *C(penRBcPtr, '•OpenRecHndl; 
V 

Openftoc MyOpenParama - [O ( 0,OD; 

/" for dead, Hrlte, Close, Flush 

typedef struct FilelOflec | 
Word fileRefNura; 

Ptr daEaBuffer; 

Long Int reque-stcount; 

Langint transferCount; 
I Cileiosec, "FilelOKecPtr, " 'FilelORecHndl; -/ 



EVENT.CC (main event Joop) 365 



FIlelORoc SaadParams - | 



OL, 

QxBOQOL, 

DM? 



f* flleftefMypi 
/* dataBuffer 
/* rsqueetGounc. 
/* transfei^bunt 



/<• fileRafNura 
/" dataBuffer 

/* requestCount 
/' transferCount 



/* nest remains unused V 



FilelORec WrlteParams - | 

a, 

EL, 

oxaoooi, 
at I; 

FilelORec ClnseParaxs; 

/* for Create, SetFilalnfo, GetFllelnfn 

typedef struct FileRec { 
Ptr pathname; 

Word Okcceaa; 

Word flleType; 

Lor.gint auxType; 
Word etorageType; 

Word cnateDate; 

Word createTlme; 

Word nodEater 

Word modTline; 

Longint bLocks'Jsed; 
f FlleHee, "FlleflecPtr, "FlleReeHndl; '/ 

FlieRec CreatePiruiis - ( 

OL, 

0x00=3, 

0x0006, 

GL, 

1, 

0,0, 
DLL- 

/* for Destroy, ChangePath, ClearBackupBlt , GetPathname, GetBootVol 

typedef struct PathfTameRec I 
Ptr pathname; 

Ptr newPathname; 

} PatdNameRac, *PathfJaaveRecPtr, "PathNameRecHndl; 

PathNameRec DastParams - (nL,(JL},- 

Mm'raBliHec TheEvent; 

HainEvent (J 

I 

int MyEvent; 

iheEvent.nnnTaskMasJt - DjiOaaaDfff; f* Initialise ost ■/ 

do 
I 

do 

( 
ActlvateFlag - 0; 
CheekFrontW () j 

MyEvent - Taskmaster (OjtFFFF, *TheEvenU{ 
I 

while (J MyEvent); 
switch (MyEvent! 



*/ 



-■' 
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ease aetivateEvt : DcActivat* (J ; 
break; 

case 17: /« in menu */ 

DoMenu i J ; 
break; 

case 22: /■ i n goaway •/ 

D0Cl0MIt*a{| ; 

break ,■ 

case 25r /- in special menu item •/ 

DoMer.it {> ,* 
break; 
I 
I 

while {I (OuUFlag)}; 
I 

DoQuitJteml) 
[ 

OuitFlag - OxBOOO; /♦ simple u h3 '/ 

/* Ch«ck If the front window tro changed and react accordingly */ 

CtackTrontH () 

I 

Dr.jRecHandle fempDataHar.d; 
DataRecPtr TempDataPtr; 

ThUWlndcrw - FronxNindow t) ; 

if (I [ThtBWlndow -- LastWindow) ) 
[ 
if (LsstWlndow - ThlsWlndow) /* at least one window V 

i 

If {I (GetSysWFlag (TkiiiWl ndowj ) ) 
I 
SetlfpForAppH'l) i 
If (AEtlirateFlag) 

TempDataHand - (DataRecMandle) GetWRefCon (TneEvant .wtnTaskData) ; 
else 

TompDataHand - (DataReeHandle) GotWRBfConfTMsWIndow) ; 
TampDataRtr - 'TampDataHand; 
KLQck [Tempo at aKsnd) ; 
If [lampDataPtr -> Flag) 
DtsableMltem fSavolD) ; 
else 

EnableMItera (SavelDl ; 
HUnlock [TempDataHandJ ; 
I 

SlSe 

SetUpForDawt) ; 
} 
alsa 

DisableAll (); 
I 
I 

DS»Etlt*t«0 

If (TheZvent . wmMadiriers i 1) 
I 
fcctlvateflag - If 






EVENT.CC (main event loop) 3S7 



Check Front W 0; 



/* Disable Items not applicable */ 



DisabloA.ll (1 

[ 

SetMenuFlag 
DrawMenuBar 



(OxOOBO.EdltMenuIDl ; 

IS; 



Disablel terns (); 



/* disable ■/ 



SetUpForAppW (1 
I 

SetMenuFlag {0*OOBG,EdltMenuIDI ; 
DrawKenuBar t! t 
Enable Items (I ; 
I 

SetUpForDaWl) 
I 

Dl sab lei terns O; 

EnableMIten (ClnseWDl ; 

SetMenuFlan; (Onf m,EdittfenuID) t 

DrawMenuBar (J ,- 



EnableltemsO 
I 

Er.ableMlten (savelD) ; 
EnaMeMItem.(CloBeHID) ; 
If (PManaaerFuujid) 
1 

Enablemtao {prlmlD} ; 
EnableMtm (SetUpID) ; 
i 



/* don't enable If printing V 

J* Is out of tha question] */ 



DlsaMeltejiis f ) 
1 

DisableMItera (Save ID) ,- 

□ IsableHItem (CloseWID) ; 

DisablBMltem (Print ID| ; 

DisableMItera (SetUpip) ; 



/* Who cares!? V 



/* Now some I/O stuff, this file Is just Ox for It V 



booLean laadOr.eO 

I 

OPEN (*MyppcrJa 
if ( tcmlErr) 



I; 



} 

else 

1 



CheckDlsxError (1) ; 
return (FALSE); 



/* couldn't open */ 



ReadParans. fileRefN'um - MyOpenParaitifi.gpenReOIum; 
ciD3EPsra.T.s.fileRefNim - MyOpenParams.openRefNura,- 
MAD (tBeadParanns) ; 
if ( toolErr) 



I 



CLOSE (seioseParams) ; 
ChecJtDlskError [3) f 
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return (FA1SE); 

] 

else 

( 

ciflSE((CLoseParams) ; 
return (TRLTEJ ; 

) 
) 

I 

SaveOne ( ) 
I 

criatePaxans.pathname - MyOpenParajns.openPathiiajBs; 

De»t Pa rams .pathname - WyOpanEarams.openPathname; 

CloisParaBiB-.fileRefNuic - KyCpenParams.oper.RefNiur.; 

CreateParams.file'IypE - Oxci; 

CreateParams.auitType - 0; 

Destroy | i. De st P arams ) ; 

CREATE [ (Create Pa rams) ; 
If ( toolErr) 
I " 

CLOSE {iCinseParnniBj ; 
CheclsDliJcError ( J} ; 
I 

61 SB 

[ 

OPEN {(KyDper.ParansI f 
it (toolErrJ 

[ 

CLOSE (* Close Pa rams) ; 
ChackDisJtError (4) ; 
] 
s?" ■( 

^ 

KclteParama, f lleteftfum - MyopenParajns.openKeiNuni; 
WRITE (IWrlteParams ) ; 
If (_toolErr) 
[ 
CLOSE (sCloseParajna) ; 
CheekDlskError{5) ; 
} 
else 

CLOSE ftCloseParamsi ; 

I 
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W1NDOW.CC (windows) 



f*** ** #** ***##** ft* * 4ft ** ft ft****************** ***** **** ft ftft* ftft ft ft* • • ft ft ft * * * * 

* HodgePoJge; An example Apple IIGS Desktop application 



copyright (©) 19B6-B7 by Apple Computer, Inc. 
AH Rights Reserved 



• source rile WINDOW. CC -- Window opening / closing * 
■ * 

t ■ a a a fe • ftft ft ftft ft •»* ***** *** ft ft ftftftftft ft ft ftft ft -ft ft ft ft ft ft ft ft * ft ft ft* ft | ft ft , ft ft | ft ft ft ft ft A A * * ft * * ^» 

• Include <types.h> 
(Include <aulc)tdraw.h> 
(Include <wlndow,h> 
•include <stdftle.h> 
(Include <piodoa.h> 
(Include <asernory,h> 
(Include <qd3ux.h3 
(Include <font.h> 
(include <manu.h> 
(include <desk. h? 
(Include <jniactool.h> 
(Include <texttDol .h> 
(include <intniath.hi 
(include "hp.h" 

CKtcrn GrafPartPtr Origport; 

extern char str[]; 

/' stuff to define the window data structure, defined in HP.H 

typedef struct Sara Hoc ( 

handle Flcfland; 

char Blank; 

char str [3D| ; 

char mstuff[6]; 

Byte Flag; 

char Extra; 

I DataRec, -*DataRecPtr, •'DataRecHandle; 
*/ 

DataHecHar.dle MyDat a Handle; 
DataRecPtr RefPtr; 

/* This structure Is defined in window. h 
typedef struct WtwaskRec { 

Word wmKhat ; 

DblWord wnttes^aae; 

DblWord MnWhan; 

Point wmKhere; 

Word wnMca: tiers; 

DblWord! wmTaskData; 

DblWord wnTaskMask; 

I WnTasltRac, 'WBiTaBlcaecPtr, **VftnTaskRecHndl; ■/ 

•Kt*rn WmTaaicRec TheEvent; 
eittern char *LlneTabl6[] ; 
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extern int _toolErr; 
extern lnt MylD; 
extern int ThlSModai 

extern GetPutTamplate Sfpfi^QTemp; /» templates for StdFlle V 

thzr DriijitemU - "—Mo Windows AllocatedWNZSSW; /* first item In windows */ 



extern int ManoFlaq; 

extern FontlD DesiradFont; 

•xtern int Eaint r 

extern int DispFontWindow () ; 

piical int OpenFllLer [H 



f* see Font . c 

y* it h « */ 

(* window content proc */ 
/* Window def Proc for fonts *f 



1* typedef struct FaraitList \ 


Integer 


paramLengthf 


Word 


wFrajneBltfi; 


ptr 


wlitle; 


long 


wRsfCon,' 


Senr 


wZecm; 


Ptr 


wCqlprj 


Integer 


wiQrigin; 


Integer 


wXOrigin; 


Int agar 


vDataH; 


Integer 


wDataW; 


Integer 


wftaxH; 


Integer 


HHudt) 


Integer 


wSeroltVer; 


Integer 


KScroliHor; 


Integer 


wtagever? 


Integer 


wPageHor,* 


Dblttord 


wlnloBefCon; 


Integer 


wlnfoHeight; 


Ptr 


vFramaDefProc," 


Ptr 


wmfoDef Proe; 


Ptr 


wCont Def Proc; 


tueet 


"Position; 


mortsti 


wPlane; 


wind Rec Ptr 


wSterage,- 


1 raramLiat 


, *Paraj!LListptr, "'ParamlistHndl; */ 


PariraList Mywindow - 1 




sizecf (Myw;nda«) , /* Hecoid slxa »/ 




0*ddaO, /» Frante ddaO »/ 




01, /« Ptr to tltla */ 




01, /* HefCon *l 




0,0, D,0, /* Full Eke ( o — > default!*/ 




Oi, /* Color Table Ptr */ 




0, /« Vortical Origin */ 




0, /* Horizontal Origin */ 




200, /* Data area night */ 




640, /> Data area width */ 




100, /* Max cent height */ 




640, /- max cant width *f 




a, f pixels to scroll vert *( 




16, /* pixels to scroll horz '/ 




40, /* pixels to page vert *( 




160, f pixels to paga horz V 




QL, /* info bar string */ 




0, /* info bar height */ 




01, /' def proe ptr «/ 




t>L, /* Info bar def proc */ 




Paint, 1* Content def proc ■/ 




0,0,0,0, /* siie/pos of content */ 




-1L, f* plana of window */ 




01; f* Wind Rec add */ 



WINDOW.CC (windows) 



391 



extern rilolQRec ReadParams; 
extern FilelQRec HrLeeParanis; 

Beet ISizPos - 120,10,80, 35a \; 

(* 

typedef struct FonrlnfoRecerd \ 

Integer as cant; 

integer descent; 

Integer wldMax; 

integer leading; 
I Fontlnfofteeord, *FajitlnioRecPtr r "FontlnfoRecHndl; 
•/ 



ForttlnfoHecord FI Record; 
sfReplyRec KyBeply - [0,0,0," 

ant em OpenRec MyOpenPirajns; 



char Promptl [] - "VpLosd which picturaj"; 

char Prompts [] - "\ P Save which picture:"; 

int Wxoffset - 20; 
int. Kyoffset - 12; 

handle PIcHandle; 

extern boolean OpenWindowO ; 

extern boolean Ast'Jser ; 

extern boolean loadItU.pl); 

extern boolean DaTheOpen j) ; 

GrafFortPtr WhichWlndow; 

GrafPortPtr WlndowLl«[lSM 

lnt vlndex; 

GrafFortPtr vT*ble[16]; 

Int Wtr.dex - Q; 



/* OpenRec [ 

int openReiKupi; 
ptr openFathname; 
long 103'jffer; 
I */ 



/* handle to picture data V 
/* to add window to raenu V 



/* current window handle *f 
/* list of window handles '/ 
/* index to: | *; 

/* list nf what was visible ■/ 
/■ Index to next avail wind id"/ 



Loclnfo Srclnfo640 



0x00, 

/* used to be byte here */ 

OL, 
160, 

(0,0,200,640) 



R£ct SrcHectMO - [0,0,200,640); 



/. „»™^ _ — „ 

f* Now the real stuff 

/• Procedure to Close windows, we close them from the back. 
Things move faster this way. 
V 
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HldeAllWlndews I) 

t 

ulndex - 0; /* init index *t 

if (viable [vlndex] - Front Hindoo I) ) /*at least one window */ 

[ 

■ for (vlndejt.-vTableJulfide* H] - GetNej(tWindow(vTatjle[vIndepU ) ;vliidex") ,- 

for (vlndex.-vlndex >- 0;v Index — I 
NldeWlndow (viable [vZr.dex | ) ; 
I 
I 



f* DOOpenltejn: 

lj Make sure chat there aren't too many windows open already; 

2) Call OpenWindow to let the user see it; if successful, 

3) Call AddroMenu to add the name to the windows menu list. 
'/ 



DoDpenltor.O 
I 



I 



if (Wlndex — HUM WINDOWS) 

HanyWlndDlalog (J; 
else 

if (OpenWindow 0) 
AddToMenu ; 



/* Oper.window; 

II Calls SFGetFile to get name of file to display in window 

tor the did log to select font if needed) 
2) Get* memory for, and loads the picture/font data Into memory 
3} Allocates a new window 

I a) puts handle to KyWindowInfo in WrefCon 

b) note that wcontDefProc is set to "Paint" 
C! for fonts wContDefProc is set to "EispFo tit Window" 






The definition of MyWlr.dowJnfo Is global data. 






boolean OpenWl ndew < ) 
I 

if ((TheEvent.winTasltData C OxFFFF) -- SfcowFanCID) 

I 

if (DoChooseFont ) 
If (DoTheOpen () ) 
return (TRUE] ; 
else 

return (FALSE) ; 

return (FALSE) ; 
I 
else 

I 

if (AskUserO ) 

return (TRUEI; 
else 

return (FALSE); 



WINDOW.CC (windows) 393 



/■ 

typedef struct SFReplyR ec [ 
Boolean good; 

Word filerype; 

Word auxFlleType; 

char filename [lSjj 

I SFRepiyRec, *SFReplyRecftr ; 
boolean AsJcUser () 

if [LnadltTJpO ) 
return (TBUE) ; 
else 

return (FALSE) ; 
else 

rat urn. (FALSE); 

boolean loadltUpO 
WaltCursor(); 

PicHandle - NewHandla (OxSuQOl.MylD, 0, OH - 
if (_toolErr) 

return (FALSE) ,- 
else 
I 
teadparanu. flat aBuf far - 'FJcMandle- 
BXoek (pidtandlB) ; 
if (DoTheOpen{) I 
return {TRUE]? 
else 

return (FALSE) ; 
I 
1 

boolean DoTneOpeno 

int auj(l f aux2; 

ptr aux; 

boolean lOError - FALSE; 

Int I; 

n there is always a need »/ 
long riDAuaj 

MyEataHandle - (BataReckandle, Needle ( UongMslz.of fDitaRec] , 
MyWind^.„ Refn3n , tl^JJfyOat.JfaMle; *"*««»»*<»» J 

if I_toolErr) 

ret um f FALSE ); 
else 
i 
RefPtr - "HyDataflandle; 
HLoclc (MyWindow.wRafCon); 

/* The « wlgB ts that tne window la for a pictu ^ (not ^ ^ ^ 
r±ag "' i" picture flag »/ 
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If I (TheEver.t .vroTaskData ( Oxffff) — ShowFentlD) /* werE we right? */ 
I 

RefPtr -> Flag - Djtl | MonnFlag; /* No! so change */ 

PicHandle - (handle) ( (DasiredFont.IamHuai) + 

(DeslredFont.fcntSize * OxlOOOOOD) + 
(DesiredFont.fontStyle * OxlOOCO) J ; 
/* everything; to font */ 

f display ■/ 

KyHindoM.wCDnt.DelE 1 roc - fVoidEracPtr ) DispFontKirLdcv; 

I 

else 
( 

MyQpHr.Params.epenFathnama - Myfteply. full Path name; 

if ("(LoadOnel) )) 
lOError - TRUE; 
I /* end of picture stuff V 

if <IC£rror) 
I 
DlsposaHandle iMyWlndow.wRefConl ; 
GisposeHandle (PlcHartdle) ; 
return (FALSE} ,- 
I 
else 
[ 
flefPtr -i PicHand - EicHandlo; 
RefPtr -> Blank - 0*20; 
MyWlndow.w.Title - RefPtr -> Str; 

if 11 (MyReply. filename [Q] <- HaxNaraeSize) J 

MyRepiy.fllename[Q] - HanNameSl le; 
for {i-MyRepLy.fllenaHieEO];i>-a.-l— ) 

RefPtr -> Str[i] - MyHeply.riienajr,e[lJ } 

MyWlrcdow.wDataW - 610; 

KyWindow.wMaxW - 64 0; 

I$i2pcs.h2 - 350; 

My Window. wDataH - 200; /* In case is a picture */ 

SetPort (OrlgPort) ; 

If ( (TheEver.t.wmTasltData & DxFFFF) — ShourFnntTD) 

FIDAux - GetFontlDt); 

InatailFant (PIcHar.dle, 0) ; 

GetFontlnfo (iFlHeecrd) ; 

MyHindOw.tfDataH - 

( (FIReeord. ascent + FIReeord. descent) * (NianLlnes + 1)); 

FindHaxwidth (J ; 

Insta HFont (FIDAux, 0} ,- 
) 

/* windows have to offset evenly */ 
Mywifidow.wPosltlan.vl - Wyoffset+ISliPo'S.vl 
MyWindow.wPosltlon.hl - WxofEset+ISliPos.hl 
MyWltidow.wPosition.if2 - Wyoff set+ISltPos.v2 
MyWindow.wP<3filtlon.h2 - wxoflset+lsiiPpg.hi 

Wxoffset +- 20; 

lf [(Wyoifset t- 12) ? 120) 
Wyoffset - 12; 
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WhlchWindow - NewKlndcw liMyWlTidow) ; 

SetPort (OrlgPort} ; 

Bfflllock ttiCHJmdU) I 

SetOrlglflMaBk (DkFFFE, WhlchWindow) ; 

InltCursorlJ; 

return tlROE) ; /* dually l ■/ 

I 
I 
I 

void DosavettemO 

I 

DataRecHandle AuxKandle; 

Pointer AuxPtr: 

Int i; 

HhlchHlndbU - FrnntWindDW [) ; 

AuxKandle - (QataRacHandle) ffetWHefCon (WhlchWindow) ; 

RafPtr - 'AuxKandle; 
HLock {AUKHandle) ,- 



If (!(RefEtr -> Flag)) /* save only type D windows »/ 

[ 
MyOpenPararaa.openFathnai&e - GetWTit 1b (WhlchWindow) ; 
SFPutFlle (20, 20 , Frotnpii.MyOpenParams . oponPathnairie, 15 , sMyReply) ; 
If (MyHeply.good) /• <> a — > OK to save It V 

{ 

Walt Cursor () ; 

PieHandlo - Sefptr -» PleHand; 

WrlteParanm.dataBufrtr - "FicHandle; 

HLocktPicHandle); 

MyCpenFarams.openPathname - MyReply.fuUPathname; 

SaveOneO; /* save the picture */ 

for (i - HyReply..fllanameiO];l >- 0; i— ) 

HefPtr -> str[i] - MyReply. fllename[ij ; 
SetWTltle (Hef Ptjr -> Str, WhlchWindow) ; 
HUnlock (PlcHandle] ; 
CalcMenuSlzfl (DL,wlrtdnusHenuI[>) ; 
InltCursorU ; 
1 
] 



] 



/• This routine finds out how wide the window should be for the 

current font 
•/ 

FindMaxwldthO 

I 

Int teropFlaos; 

int LinaCoimter: 

Int aux; 
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HyWindow.wDataW - 0; 
tempFlags - GetFontFlagsd J 
SetFontFlags ( (Sef Ptr -> Flag » lj ( 11; 

for (LineCounter - lrLineCounter < NumLines,-LineCount.er++) 
If ( (aux - StrlngWldtJilLinersMelLlneCounter])! > HyWinctow.wPataW! 
KyWindow.wDataW - aux; 
Hywlndow.wD/ataH t- 10; 

Set "ontFlags IteRipFMatjal ; /" put flags back •/ 

I 

I close a. window and dispose of extra-data (In WRetCom) 

and remove It from window list 
V 

DoCloseltemO 

I 

DataFecHandle tetnpKand2; 

DataRaeFtr tempE>tr2; 



lnt IDDelete; 
int Counter; 
lnt IDStart; 
lnt IDWew; 



if (WhichWindo* - Frantwindow 01 
I 
ClosefjnAByWlr.Ptr (Whlchwindowl ; f* If it's a eya wind this la enough*/ 
If ( toolErr) y* error means wasn't a systefti tfirtddW */ 

[ ~ 
tampHandl - (DataHeeHandle) GatWHafConjWhlenWindowI ; 
t«mpPtr2 - *tempHand2; /• dsref */ 

KLocx [ter,pHar,ii2! ; (* and lock It */ 

PlcKandle - tempPtr! -> PicHand; /* handle to get rid of"/ 



If (tempPtrZ -> Flag! 

ficKandle - NIL; 
iDDelete - Mjwlndd + 300; 
If (Wlndax -- 1! 



/» -0 — > font */ 

/* so, don't dlapoae */ 

/* take it out Of list ■/ 

f* era wind is special case "/ 



•: 



InaarLMlcew (origltem, 0,WindowsMenulDl ? /• no windows, message*/ 
SetKejmFldfllQjiDDeOjWtndowaKenuID) ; /* disable windows */ 

DrawHenuBar () ; 



WJtolfset - m 
Wyoffsec - 12; 

] 
DeleteKlteraUDDelete) ; 
W index — ; 



/* reset start */ 

/• for window sizing •/ 

/* off the menu. */ 



if (Counter - Hlndex) 



i 



IDStart - 300 i 
IDNew - 300; 

while (counter} 
I 

if (IDStart 



/' starting point V 



IDDeleta) 



i 



SetMTtemlD (IDNew, IDStart) ; 

IBWewn; 

Counter — ; 



IDStart+-; 
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^lOfeiiuslze (OL,Hl n dQwsM en arn) ■ 
DJsposoHandle (tempHandZ) ■ 
it (Plcffandla) 

DisposeKandle(PicHaridle) • 
ClcseHLndoHtifflicMfl.nd.cw,. 

) 
J 

AdJWlndjj 

I 

int IDComiter, l,y; 

1 - Wtr.deK -l; 
IDCounter - i; 

*"; f ' ( <"■***■** ._ HJndDWLlst[ln , , i < ojj 

y - i- 

ttindowLiatfy] - windowLlstr v + ,,. 

J 

return (i|; 
1 

•/ 

faint () 

! 

DatafiecHandle auxHandle; 

GrafPertPtr auxPtf; 

DataRecPtr DataPtr,- 

auxptr - GetPort (J ■ 

auaHaiidle . HtataRecHawjle, G et WR e fr orl ,''„*? SU *™ nt P° rt *' 

DataPtr - 'auxHandle; GetKR efc™ {auJ1 . Pt r) ; ,. hanflla £o ^ 

HIacfc {auxHandle) ; 

HUnlock (aun Handle) ; 

PaintltfiialntJiand) 
handle Paintnarid; 



per au«Ptr2f 

•wiPtri - 'PaUithand; 



/* de^ef v 
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HLock IPalnthandl ; 

SrcIivfoSJD^perToPlxiitiage - auXPtr?; 
PPToFort ((Srclnf o£40, iSrcRect 640, 0, 0, 0) ; 

HUnlock (Paint handl; 

I 

DoGoftway ( ) 
I 
HideWindgw (TheEvent .wmTasJtData) ; 

I 

DSHLndawO 

t 
Select Win daw [WhlchWl ndov) ; 
SHowWlndow (WhicbWindow) ; 



' 



?as:sl lnt OpenFllter (DlrEntry) 

Jtr DlrEntry; 

/* Filter function called by the standard File Operations 1 SFPetFlle 
dialog to determine whether a filename should be dimmed or not. */ 



I 



If ( (* (DlrEntry + Quid! i BxOCET] — OxCl) f* Type SCI: picture file V 

rat urn (J); /» ... so It's undiirmed. »/ 

alee 

return (1); /' Elae show it dimmed. */ 
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/imtmtutiHtii* >•»>..».„•, miHioii mi 

ft 

Hodgepodge: An example Apple iigs Desktop application 



Copyright (c) 1986-87 by Apple Computer, Inc. 
All Rights Reserved 









Source file DIALOG. ce — Dialogs and error trapping 



(include 
I ir.cl-jdc 
♦include 
(Include 
I Include 
(include 
'Include 
(include 
(Include 
(include 
•include 
(include 
(include 



<'ypes,n> 

<quickdraw.h> 

<qdau*.h> 

<memory.h> 

<dlaleg,iv> 

<prodoa.h> 

<;teKttool,h> 

<3tdflle.h> 

<wlndQi»\h> 

<leeatcr,h> 

<lnttnath.h> 

<misctool.h> 

"hp.h" 



extern int 
extern int 
extern GrafPortPtr 



topjErr: 
MylD; 
OrigPort; 



GrafPortPtr 



MsgwindPtr; 



/» Data structure for "About Hodge Podge.. .» dialog box: •/ 

static char OKStr [] - "\ P QK"; 

Rect DRsct - (20,180,192,450); 

Rect ApplelconRect - (135, 2E,0, 0] ; 



400 Appendix F: HodgePodge Source Code: C 



phar Applelcon640[] - 10x00, OxDO, 0x50, 0x00,0x22, DxOO, 0x40, Ojt«0. 

tlxDO,DxOO, DxOO, 0x00,0x00, 0x00, 0x00, 0*00,0*00, OxOD, 0x00, OxQO, OxOO, DxOO, OxOD, 0*00, 

oxDf ,ox(f , oxff, oxf f , Dxf f , oxrf , oxf t, oxf f , oxff , oxf r,o*f r,oxff , oxf f, oxff , oxf f , oxf a, 

0x6 J, OxOC , OxCQ, OxOO, 0x00, 0x00 , 0x00, OxOO , 0x00 , OxOO, DxOO, OxOO, 0X00, OxOC , oxca , oxrc , 

Dxof,o*or,oxff r oxff,axff,oxff,cxff,axrr,oxrf,oxff,Dxff r oxff,oxf£,axrf,oxfa,ox£D, 

O*0f,axl!>', Oxff, Oxff, Oxf r, Oxff, Oxff, Oxff, Oxff, Oxff, 0x£8, OxBf, Oxff, Oxff, OxfO, GxID, 
OxDf, OxOf, Ox f f , Oxf f , Oxf f , Oxf I, Dxf f , Oxf E, Duff , Oxf 8, 0x86, OxBf , Oxf f , Oxf f , Ox JO, Oxf 0, 
OxOf, OxOf , Oxf f, Oxf f , Oxff , Oxf f, Oxff, Oxf f, Oxf f, OxBB, 0x88, OxBf , Oxf f, Oxf f, Oxf 0, Oxf 0, 
Ml , B*0£, Oxf f, Oxff, Oxff , Oxf f , Oxff, Oxf f ,0xf8, OxBB, 0x88. Oxff , 0*f f, Oxff, OxfO, OxfO, 
Elf, OlOf, Oxff, Oxf f , Oxff, Oxff, Cxf f , Oxff, OxBB, 0x68, 0x88, Oxf f ,Cxf f , Oxf t, OxfO, OxfO, 
(MI, OxOf, Oxff, Oxff, Oxff, Oxff, Oxf f,Cxff, 0x88, 0x68, OxBf, Oxff , Oxff, Cxf f, OxfO, OxfO, 
0*0f ,OxDf ,Oxf f , Oxf f , Oxff, Oxff, Dxf f, Oxf f, 0x88,0x88, Oxff, Oxff, Oxff ,Oxff , Oxf D, Oxf 0, 
Dx0f,0x0£ , Oxff, Oxff,QxfB, OxaB, OxBf, Oxf 1,0x38, Oxff, 0x88, 0x88, Oxf f, Oxf f ,CxfO, OxfO, 
OxOf,OxQf,Dx£f, OxfB.QxBB, OxBB, 0x88, OxSf, Oxff, 0x89, OxBB, OxBB, 0x86, Oxff, OxfO, OxfO, 
QxOf ,OxOf, Oxf r, OxBB, 0x86,0x88, 0x88,0x88, OxBB, 0x88, Sx6B, OXBB, OxSB, OxBf, DxfO, OxfO, 

BsCf , OxOf , Oxre, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxe f , Oxf f , OxEO , Oxf 0, 
0«0£, OxDf, SxEe, Oxee, Oxee, Dxee, Oxeo, Oxee, Qxee, Oxoo, Oxee, Oxee, Oxf f, Oxff , Oxf ;, Oxf 0, 

OxOf , OxOf , Oxf e, Oxee, Oxee, Oxee, Oxee, Oxao, Oxee, Oxee, Oxee, Oxet, Oxff, Oxff, Oxf D, OxfO, 
OxOf, OxOf, Oxf fi, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, OxSf , Oxff, Oxf f, OxfO, OxfO, 
OxOE.OxOf , Oxf 6, 0x66,0x66, 0x65, 0x66, 0x66, 0x66, 0x66, 0x66, 0x6f, Oxf f, Oxff, Oxf 0, OxfO, 
IJxOf, OxQf, Oxf 6, 0x66, 0xfi6, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, Ox6f, Oxff, Oxff, OxfO, OxfO, 
Glflf, OxDf, Cxf 4, 0x44,0x44, 0*44, 0x44,0x44,0x44,0x44, 0x44, 0x44, Oxf f,Ox£r, OxfO, Oxf 0, 
0xCf,0xDf, Dxf4, 0x44,0x44, 0x44, 0x44, 0x44,0x44, 0x44, 0x44, Dx44,0x4£, Dxf f, OxfO, OxfO, 
OxOf,OxOf, Oxff, 0x44, 0x44, 0x44. 0x44, 0x44, 0x44,0x44,0x44,0x44, 0x44, Ox4f, OxfO, OxfO, 

DxOf.OxOf.Oxff, 0x55,0x55, 0x55, 0x55, 0x55, Dx55, 0x55, 0x55, 0x55, 0x55, Qx5f, OxfO, OxfO, 
QxOf, OxOf, Oxff, 0*55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55 ,0x55, 0x55, 0x55, Qx5f, OxfO, OxfO. 

OxOf, OxOf, Oxff, OxE5, 0x55, 0x55, 0x55, 0*55, 0x55 ,0x55, 0x55, 0x55, 0*55, Oxff, OxfO, C-x£0, 

OxOf , OxOf , Oxf £, Oxf 1 , Oxll, Oxll, 0*11, Oxll , Oxll , Oxll, 0x11 , Oxll, Oxll, Dxf f, OxfO, OxfO, 
DxOf, OxOf, Oxff, Oxf £,Oxll, Oxll, Oxll, Oxll, Oxll, Oxll, Oxll, Oxll, Oxl £, Oxff. OxfO, OxfO, 
OxDf, OxOf, Oxf f, Oxff, Oxf 1,0x11, Oxll, Oxl f, Oxf f,Dxll, Oxll, Oxll, Oxff, Oxff .OxfO, OxfO, 
OxOf ,OxOf , Oxf f,Oxf f ,OxfF, Oxll, Oxll, Oxff, Oxff, Oxf 1, Oxll, OxlF, Oxf f , Oxf f , OxfO, OxfO, 
OxOf, OxDf , Oxf t, Oxff, Oxff, Oxff, Dxff,Oxf f ,Oxf f , Oxf £, Oxf f, Oxff , Dxff,Cxf f, OxfO, Oxf 0, 
OxDf, 0x00, 0x00,0x00,0x00, OxOD, DxOO, 0x00, OxOD, 0x00, 0x00, 0x00, 0*00,0x00,0x00,0x10, 
OxDf , Oxff, Oxf f, Oxff, Oxfr, Oxff, Oxff, Dx£f ,Oxff , Oxff, Oxf f, Oxff , Oxff, Dx££, Dx£f , OxfO, 
DxCO,OxOO, 0x00, 0x00, OxDO, OxDO, 0x00, 0x00, DxOO, 0x00,0x00,0x00, 0x00, OxOO, DxOO, 0x00 

H 



Rect TextlRect - 112,4,200,25 6}; 

/• Thla la L«iGSTATrEXT2-f omitted type text: -/ 

cJiir Textl [] - "\1J\1\0\ 

\ls\C10W\ 

HodijePodgE In C\ 

\z\ 

\T\ 

U5\0\D\ 

A pgtpourrl nf routines that demonstrates many \ 

features of the Apple 11GS tools A 

\t\ 

\t\ 

By Che Apple IIGS Davfllopment Team\ 

\r\ 

\c\ 

Copyright Apple Computer, Inc., 198 6-1 987, \ 

\r\ 

All rights reserved V 

\r\ 

vt.O October 1987"; 



Heet ButtonRect - 1153,180,0,0],- 
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/* Dialog Template data structure for "Please wait while ...» dialog; •/ 
shar PlsKtMsg [] - -\pplease wait while we set things up."; 



ItemTeRiplate Plstftltam - |134S, 

15,70,200, 640, 

StatTut, 

PlsMtMsg, 

NULL}; 

DlalogTamplate PlsWtTemp - (30, 120, 80, 5ZD, 

true, 
NULL, 

(PlaWUtem, 
NULL}; 



/' Alert Template data structure for too many windows and disk Error alerts: -/ 

ItemTBitrplate ourAlertlteml - {l, 

25,320,0,0, 

inittonlteni, 

OKstr, 

0, 

o, 

NULL}; 

ItemTemplate 0urAlertItem2 - U348, 

11,72,200,640, 

stat Teat, 

"DLL, /• IteroDescr — will fl:i it in •/ 

0, 

0, 

NULL | ; 

AlertraiBpJate OuxAl err reap «■ [3D, 120, B-0, Szrj, 

666«, 

0x80, 0*80, 0x80,0x80, 
(OtirAlertlteml, 
SOUrfllertlteniZ, 
MULL |; 



Checkroel Error (Whare) 

t* Chaebol Error qhecks to Sfla u th> lfl3t toQl csU cofflpUl . ed SUccES3fulJ 

It !?' ^ i \ 3lJst «"M- « ^t. «e crash using the System Death 
Handler (bouncing apple > , "/ 



I 



lnt HJiere; 



static char DeathMsg l] - -\p At SXXMt,- Could not handle error ?■'■ 
lnt Tool Error Save; 
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ToolErrorsave - _toolErr; 

if IToolErrorSavej 

{ 

lnt2Hex (Where, D eat hMsg + 6,4>; 

SysFallMgr (ToolErrorSave.DeathMsg.! , 



boolean CheekDiskError [Where) 

/* This routine checks If the last ProDOS operation caused an error. If so, 
then we change the cursor to the arrow cursor, put up a stop alert dialog 
box with the text of the error message, which then waits for the user's 
OK click, and then change the cursor back to the wristwatch. If there 
was no disk error, then we do nothing. We also return 1RUE or FALSE 
depending or. whether an error actually occurred or not, v 

lnt Where; 



I 



lnt DlskErrNum; 

DlskErrHum - JtcolErr; 
if (DlskErxNuml 



/• Save thla first -/ 






OurAlertlteml.ltemDescr - "\pBisk Error 5XXXX occurred at 5XXXX."; 
IntiHex {DiskErrNum, f* put ASCII ■/ 

OurAlertltemj.itemDoacr + 13, 

«}; 

Iftt2flen (Where, /• put ASCII •/ 

OurAlertltenu}, ItemDescr + 31, 
41; 

Initcursor (); /'Set arrow cursor »/ 

StopAiert (sOurAlertTenp,NlJLL) ,• /» Draw dialog t wait */ 

/* Do not restore watch cursor */ 



I 

return (DlskErrNum] ; 



f* Assign function resuLt */ 



ManyWindDlalog () 

/* Displays caution alert dialog with a message about no more windows 

being allowed open. Handles mouse events until OK button is clicked. 

Then the dialog boa is removed and we return, */ 



I 



OurAlertlternJ . ItemDescr - "\pNo more windows, please."; f* sot string V 
CautlanAlert (iOurAlertTemp.NULL) ; /* Do draw, wait, undraw. ■/ 



EoAbouelteai (> 

/' Function DoAboutltem shows how to build a dialog box manually. */ 



i 



handle ApplelconH; 

GrafPortPtr MdlaloqPtr; 

AppialconH - NewHandle (552L,KytD,0,0L) t 
CheckToolError (50) ; 

WLock (ApplelconH) ; 

PtrToHand (Appleloonfi'iu, ApplelconH, 5S2L! ; 






i* Allocate memory */ 

/* Hope it was ok •/ 

/* Freeze handle '/ 

/* Move icon Image */ 
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I 



MdialogPtr - NawModaimalcg I«DRacc.TH[fE,Ol); f Draw dialog bq« -/ 

1* Install arc! draw items In the dialog box; •/ 

NewDitem U*Jlalogttf,l 1 (Bjc.conBfii=t,buttonItam,OKStr r 0,0 1 lB)I.I)' 

Ne W 0Item ««Ul^tr, 3. *A PP l e l C onn ec t, Itonltem+UemDlsaole 

ApplelconH, 0, 0, 01) ; 
NewSlt^ <MclUlogetr,fl,iT.«iB.«, tlmBStl „„ | .j +ltel|i , lMhl 

sUeof (Tex;:) - 3,0,01) ; ' 

ModalDlalog (NULL); /. Track the „,„„ lnJ . i{je 

DisposeHandle [Apple IconHj ; /. Deallocate nemory -/ 



/' JliewPleaseWait / HidePleaaeWalt •/ 

/■ Brings up a window and puts a message on It 
witout waiting for Update Event »/ 

ShowP lease-Wait () 
I 

OrigPnrt - GetFort (}; 

MsgwindPtr - GetKe»«odalDialog ((PlsWtremp) * 

BeglnUpdato (MsgWlndPLr> ; /* hm , _ rT~«,-. __ 

ttrawDlaloo. [M s ,WindFtr) ; ^^ Upd3 ' 6 p - Dcess *' 

EndUpdate (MsgWlndPtr! ; 



HldePleaseWalt () 
[ 

CldseDlalog [MsgwindPtr) ; 

Sat Port (OrigPort) ; 

1 



MountBootDisk [) 

/■ nn.iujtactDi>k is called whenever the application require 

something from the boot volume and It Is not online ., 

I 

static char Prompt Etr [j - -\ pP i eaae lnsert lhe ^ fc . 

OKStr [l . ^ p0K «, 

CancelStr [] - "\psfiut Down" 
VolStr [256] ; 

Static PathMaraafcec CBVPar^ - | VolStt.mjLl ), 

GET_BDQT_VOL (tGBVPirams) ; 

return (TLMountVoI^e <«4 l M,Pr« B ptstr,V a i a tr,OBtt,c a n Ce istr|),- 
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FONT.CC (fonts) 



HodgePodga: An enamplB Apple Iigs Desktop application 



Copyright (c) 198B-B7 by Apple computer, Inc. 
All Rights Reserved 



Source file FONT.CC — Choosing font, £ont window defproc » 

(include <types.h> 

tlnelude <quicitdrav.h> 

(include <iont.h> 

I In elude t£ntmath.h> 

(Include <fltdflie.hi 

'include <tfindow.h> 

UncludE <memory.'h> 

(Include <menu,h> 

(Include <tenttoel,h> 

(Include -hp^h" 

extern SFReplyftec MyHeply; 

/' 

typedEf struct SFReplyRec j 

Boolean good; 

Word file-Type; 

Word au*TlleTyp«; 

char filename [161; 

char fullPatriname[l29] ; 

\ SFReplyRec, 'SFRtplyRecPtj- ; 



extern Int _toolErr; 

ptr FontWlnPtr; 

t* 

typedef struct FontID | 

Word famNum; 

Byte TontStyle; 

Byte font Else; 

I Font ID, *FontIDPtr, ••FontlDHndl; 
'/ 

FontlQ DesiredFont - ( Oxtlte, Q0,0k0B| ; 
Int MonoFlag - 0; 



typeiter atruct Font I life Record I 
integer ascent; 

integer descent; 

Integer widKax; 

lnteijer leading; 
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) FontlnfoRacord, 'FnndnroRecPEr, ** Font Info RecHndl; 
•/ 

FonLInfaRecord CurrFont; 

int Cll^^f^«iq , ht,LineCount.eI:,• 

t* 

typedef struct Point [ 

Integer v; 

Integer h; 
} Point, 'PointPtr, "PolntHndl j 
*/ 

Point CurrPos; 

chat l-l™>a[3<)j - (0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, /* Namelength + J '/ 
0,0,0,0,0,0,0,0,0,0,0,0,0,0,13]; /* + 4 for siie Info V 
char LlnelJ] - "\.0"; 

char Line2 [) - "\pThe quicit brown fox jumps ov«r the lazy dog,"; 
char Llne3[] - "\pShe sells sea shells down by the sea share. "; 
char Llne4[1 - "VO": 

char LineS [] - {32, 

0, 1, 2, 3, 4, 5, 6, 7, B, 5,10,11,12, 13, 14, 15, 
16, 17,18,19, 20, 21, 22, 23,24,25, 25,27, 78, IB, 30, 3 1,01; 

char LlneS[] - (32, 

32,33,34,35,36,37,36,39,40,41,42,43,44,45,46, n, 

48,49,50,51,52,53 r 54,55,5 6.,57,5B,59,6<J,Gl,62,G3,0]; 

char Llno7[] - {32, 

«4,S5,66«67 ( 6B,&9, 70, 71, 72, 73,74, 75,76, 77,78,1 9, 
80, 81, 82,83, 84,85 ,86, 87,88, B9, 90, 91, 92, 93, 94, 95,0); 

ehar LlneS [] - {32, 

9S, 97, 98, 99, 100, 101, 102, 103,104,405, 106, 107,108, 109, 110, 111, 
112,113,114,115,116,117,118,119,120,121,122,123,124,125,12 6,127, 
0},' 

char Llne9[] - {32, 

128,129,130,131,132,133,134,135,136,137,139,139,140,141,142,143, 

144,145,14 6,147,148,14 9,150,151,152,153,154,155,156,157,158,159, 

0j; 

char LlnelOU- (32, 

160, 161, 162, 163, 1*4,155,166, 167 ,168, 169,170,171,172,173,174,175, 
176, 177, 178, 179, IBD, 182, 112, 183, 164, 1B5, IB 6, 1B7, 188,189, 190, 191, 
0); 

char Llnell[]- (32, 

192,193,194,195,196,197,199,199,200,201,202,283,204,205,206,207, 
20H, 209, 210,211, 212,213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 

0); 

Char Linel2U- (32, 

224, 225, 22 6, 227 , 228,229, 23D, 231, 232, 233, 234, 235, 236, 237, 238, 239, 
240,2 41,24 2,243,24 4,245,2 46,247,248,249,250,251,252,253,254,255, 

char •LlnerableM - (LifteQ,Llnel,Llne2, LlneS, Line4,Une5, Llne6,Lina7, 
LlneB, Llne9,Linalfl,Llnell,Llnel2] ; 

char FroKsg[3 2] - "--DUplsy Font as Proportional \z'; 
Char MonoKsg[31]- "--Display Font as Mono-spaced^"; 
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oseFont {I 



GrsiFertPtr oldPort; 
fct tempPort [ 95 ] ; 



/* port size in bytes / 2 */ 



typedef struct FontID [ 



word 
Byte 
Byte 
I FontID, 



funKuin; 
fontstyle; 
lontSlie; 
•FontXDPtr, 



"•FontlDHndlf 



lohg tempFont; 

oldPort - GetPort () ; 



QpenPort (tentJPgrt) ; 



ChooseFont (De&l red Font, j J 



/* font changed */ 



if (tempFont 
I 

DealredFont.faniNuji! - (Word! (tempFont i Qscff 11 ) ; 
DeslredFont. font Stylo - (Byte) ( {tranpFont » 16 | I Dxff|; 
De.alredFont.fQntSlEB - (Byte) (tampFont » 2A) ; 
who cares - GetFamlnfofDesiriBdFont.faiiiNuni, 

MyReply.rilflnaine);/* Ignore result */ 
Int2Dac(DesiredFent.fontSiie, /* siie of font */ 

( (My Reply . filename) + (Myfteply . filename [ 1 ) +1) , /* position*/ 
*i /* length of result ■/ 



01* 

MyReply. filename [a ] +-4j 

ClossPort (tempPortl f 

SetPort (oidPortl; 

return (TRUE) j 
I 
else 
I 

closePort (tempFort) J 
SetPort (oldPcrtl; 
return (FALSE); 
1 



/* not signed */ 
new iegth ■/ 



/* ne« stuff »/ 



/+ Jfo change ■/ 



DiapFontWlndnw () 



f, 



/* Dont need it */ 



FontID fontld; 

FBataHecHandle FfltitHand; 
FfiaURecPtr Font Per; 

GrafPortPtr t«rg>Port; 

tenpPort - GetPort () ; /. aet curj. p^^. , f 

FontHand - (FDatsHeckandleJ GetHBefCori (tempPort) ; /* get handle to data */ 

FontPfcr - *FontHand; /* dereference i/ 

KLocl; (FontHand) i 

showFont (FontPtr -> FID,FontPtr) ; 
HunlocK (FontHand) ; 



ShowFont [fontld, Font Ptr) 

FontID f ant Id; 
FUataaeePtr FontPtr; 
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I 

word tempFiags; 

InstallFont (font Id, 0) ; 

GetFojitlnfo UCurrFont) ; 

CurrHelght - currFont. ascent + Curr Font. descant + CurrFont leading- 

« D v eT o(0,0J; ,, start ^ posit inn ., 

GetFamInfo(fonttd,fam(funi f Llne[)),- /» ignore result <•/ 

IntlDec (font Id. font size, /• slise of font */ 

(LineO)+nneOr0]+i, f* pointer to end'/ 

** ''" length of result */ 

,, -„., 0)f . /* not signed */ 

IineO(01 +-4; y. now :aft ^- h #/ 

CempFlags - Get Font Flags (I; 

set Font Flags(( [(Font etr -s Flag)) » 1) t ;); 

for (Ilnecounter - OfUneCountar < Muniiines;Lln»Countei++) 

GatEen<tCurrPos) ; 

MoueTol 5, CurrHelght + CurrPos.v) ; /» reMt * ind y ■/ 

Drawstring (LlneTablelLineCountet] ) ; 

SetFontFlags (tempFl*gsl ; 

■ 

DoSetMono ( ) 

I 

if (MonoFlag "'0x02) 

5etMItem(PrOHag,MonoID) ; 
else 

SatMItem(HonDMsg,MonoID) ; 

i 
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PRINT.CC (printing) 



Hodgepodge: An example Apple IIGS Desktop application 



Copyright (c) 19B6-B7 hy Apple Computer, Inc. 
All Bights Heserved 



Source file PHIMT.CC -- Printing stuff 



: 



(include <types..h> 

(include <3r.enory.h> 

(Include <qulckdraw,h> 

(Include ^window . h> 

•Include <print,h> 

(Include <qdaux.h> 

(include tfont.h* 

(Include "hp.h" 

extsrn. lot My ID,* 

Gr*fPortPtr WlndnnToPrint - NIL; 

kandle PrlntRecord - NIL; 

GnfPortPtr PrintPortj 

/* Csose Printer Item handler •/ 

DoChaoserltera [J 
I 

PrChoe.se r j 



'* Routine to handle page setup item */ 

Dosstupltera [) 

I 

If ([ (Print Record] > 

SetUpOe fault : 
ErstlDlalog (PrlntRecord) ; 



/* routin* to creaLe default print record */ 

SitUpDefault () 
{ 

PrlntRecord - NewHaivdle (140L,kvid, flxaoiD, OH ; 

PrDafault IPrint Record! ; 

} 

/* Now the menu item "Print" lten V 



PRINT.CC (printing) 409 



Mri-tl-emO 

if [WindenTotfrint - TYrji'-Wi-dowfif f \ y , i hf;re a window w ? rin7? */ 

if (i [21 I jlI.Hciotzq) J 

$e«pEe*a-jlt. < > ; 
it (P'.Tii'nrjiilsqiieTintSer&rUJJ 

HalLCu-ncrO ; 

ftioElfeirt - Pr^penDoc [Fr tm; tocord , U LJ .; 

f.r<lpen?agfi ( Print tort, 31.) ,- 

tra* 1'opWi :-.;J<iw ( ) j 

DrCisi&PacajiriL-.tFfjr I.} ; 

PrCiGiniCoiifvTi^rort) ; 

UsitCujjirtri) ; 



D : : w' r. rtfL nftow < : 
I 

Oat*ei*fiEa>iie Thc^f^n -nil: /i to use jitdhtly di'/r-n-l « 

nataft^pKB aaKb-tr; j»i Bl . rlJ(! |., jrc ., for pistes •# 

f Ja t-ianij? I . r Font Ft r; 

T^eKKtCtin - (Daca^e;;;anile)GetWR<::c<i.': (Wjnc&wToPriatJ ; 

a^tFLr - * These f Con; 

if temffiW -> Fi.iij) ,-*■ „< lpl ^ Eero — > font -I 

t'ozifcHaKdlis - (FrjataPjaiiisr.dleJGetH^Lir^MnCA-indo-TuPrint: ; /* .ju.-jln 
HT.r;i:Jti:FO^^]liindla) ; ,<* to u.u;:; '/ 

KoiitPLr - ^r-ontrrtndle; /* the r ia- t *j 

s^cwron- ifor.tPtr -? F"7Tl,F<ijitrir) ? /< .j> u r' ' • / 

:-:u ni o&Jt 1 F(!jilW,t nd 1 e ) ; 
;. 



Pa In 1.7 1 (nuutr-cit -> Bi&Sanfij.j 
JimiicJiCitieRjei^rj.':) r ' 



/' Ficcura Window *'/ 
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HP.H (global data) 



(include ttypes.h> 
(include <quici(draw.h> 
(include <fofit,h> 

(define SCREENMODE 0x80 
(define MAXSCAN ISO 
(define QOAuxTool 18 
(define PHanaget 19 
(dsflne HlnVor 

♦define Vol Not Found 0x45 



t* 640 mode V 

/* Auxiliary QuieSidraw */ 

/' Print Manager Tool Number ■/ 

f* Minlmun Version for them */ 



(defina NUm_MDju5 
(dsfina NUM WINDOWS 



5 
15 



I* Number of menus *t 

I* Maximum number of trindOMS ■/ 



/* Menus related defines * 

(define AppieMenuID 1 

(define :■ ileMenuID 2 

(define EdltMenulD l 

(define MrrieMenuID 4 

Mafias WindoweMeniilD 5 

♦define FontsMcnulD 6 



•define 


Undo ID 


250 


(define 


Cut ID 


251 


(define 


Copy ID 


252 


(define 


p •is- !■■: ■ 


253 


(define 


cleariD 


254 


(define 


CloaeWID 


255 


(define 


About ID 


256 


(define 


QuitID 


257 


(define 


OpenWID 


258 


(def Ine 


SavelD 


259 


(define 


ChooselD 


2 GO 


(define 


SetOpID 


.-€: 


(define 


Print IB 


262 


(define 


HCiClD 


263 


(define 


showFontlD 


264 


(define 


Mono It 


265 



/* Theses noxt 6 are standard and "7 
/* required for DA support under */ 
/« TaskMaster. V 



/* these are our own responsibility */ 



f* some font and window handling stuff */ 
(define MaXNaltieSlZH 29 

(define Numlines 13 



typedef struct BataRec | 

Char *»PicHand r ' 

char Blank; 

char Str[3Q]; 

char (MStuff [6] t 

short Flag; 

char Extra; 

J DataRee, 'DataRecFT-r, 



'DaEaRecHandle-J 



HP.H (global data) 
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/* same thing as DataRac buc far FONT windows */ 
typadef struct FentDataRac { 

char St r [30 | ■ 
char MMStuff Tfi}; 
Byte Flag; 
char E«tra; 

I FDatafl.ec, "FDataRacFtr, "FDataBecHandle; 
typede-i Int Paqkodilata [3ZQJ; 

typedef struct DirEntry 

[ 

Int PaeitedBytes; 
ward Htide; 
> Di r Entry ,- 

typadef struct XainBlk ( 

long slieOffllock; 

char UStrtS); 

word MasterMode,- 

Int PiJtelaPerScanxine; 

tnt NumfalletE; 

int PalletArr 3 y[16]ri6|; 

int NumScaiiLlnes; 

DirEntry ScanHneQirUOO] ,- 

PaekedData Packed£eanLine S [2Da] ,- 

J MsliBUc-MainBlkPtr^-MalnalkHandle,- 

'* D^y^ lt p ™ ,r " 1 inciudB ■*•«• h - ■« •" <° «« — -ith 

V 

flTndef dialog 

typedef struct ItamTenplata j 

Mora ItemlD; /* ItemTemplate - -/ 

Kect Itemfteet,- /. ItsHiTeniplate - •/ 

Word itemType; /. Itemreniplate - ■/ 

Printer ItemDescr,- /. ltel nr 8 £piata - ./ 

" caas" d0flne " e dlal ° 5 t "* lat «' — '« *"<-* «1. >« and Put 

■/ 

flfndef CatPutLlstLength 

(define GetPutLlstlength QxF /• set r» n u hi,k i .v 

(endlf l5 whlch is the max */ 

typedef struct Ga t Put Temp late [ 
Beet gpfloundsflect; 

Boolean gpVlslble; 

Longword gpHefCon; 

fr-rTf^ , 'P^^^lGetPutLlstLengthlf 
} Gat Pat Template, * Get Put Temp? tr ; 
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Appendix G 



HodgePodge Source Code; 
Pascal 



HP. PAS 414 

MENU. PAS 419 
EVENT.PAS 422 
WINDOW.PAS 425 
DIALOG.PAS 429 
FONT. PAS 434 
PRINT.PAS 437 
PAINT.PAS 439 
GLOBALS.PAS 443 
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HP. PAS (main program) 



program HodgePodge; 



Hodge-Podge: An example Apple IIGS Desktop application 

Written by the Apple IIGS Development Team 
Trar-sUted to TML Pascal by TXL Systems, Inc. 

Copyright (c) 1986-67 by Apple Conputer, Inc. 
All Rights Reserved 



This program and Its derivatives are licensed only for 
use on Apple computers. 

Works based on this program must contain and 
conspicuously display this notice. 

This software is provided for your evaluation ind to 
assist you In developing software for the Apple IIGS 
computer. 

This Is not a distribution license, Distribution of 
this and other Apple softvaro requires a separate 
license. Contact the software Licensing Department of 
Apple Computer, Inc. for details. 

DISCLAIMER OF WARRANTY 

THE SOFTWARE. IS PROVIDED "AS IS" WITHOUT 
WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, 
WITH RESPECT TO ITS MERCHANTABILITY OH ITS FITNESS 
FOR ANr PARTICULAR PURPOSE, THE ENTIRE RISK AS TO 
THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH 
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU (AND 
NOT APPLE OR AN APPLE AUTHORIZED REPRESENTATIVE} 
ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, 
REPAIR OR CORRECTION. 

Apple does not warrant that the functions 
contained in the Software will meet your requirements 
or that the operation of the Software will be 
uninterrupted or error free or that defects In the 

Software «lll be corrected. 

SOME STATES DO NOT ALLOW THE EXCLUSION 
OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAI 
NOT APPLY TO YOU. THIS WARRANTY GIVES YOU SPECIFIC 
LEGAL RIGHTS AND YOU MAY ALSO HAVE OTHER RIGHTS 
WHICH VARY FROM STATE TO STATE. 



Pascal UNIT "HP. PAS- : Main routine and tool inlt/shutdown routines 



+ 
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- 



HPIntfData, 
HPIntfProc, 

KPIntfFdas, 

clonals. 

Dialog, 

Font, 

Paint, 

Window, 

Print, 

Menu, 

Event; 



function StartOpTools : boolean; 



I HodgeFodge Apple IIGS Toolbox Interface Units] 



]HotJgePodge Code Units) 



{Routine to start up the Apple IIGS toolbox. We attempt to start up all 
the managers that we need, cheeking each time if an error occurred during 
startup. True/false is returned by this routine depending on its success. 
If the RAM-based tools cannot be loaded, the user la prompted to install 
a system disic and is given the option of trying again or emitting. The 
latter option exits this procedure with a False result. Tool startup 
errors result In a call to the system death handler (the bouncing apple), 
with a code showing where we died as well as tho actual tool error number.] 






(Needs 3 pages) 

(Needs 1} 

[Needs 1| 

[Needs II 

[Needs 1 1 

(Needs 1| 

(Needs 1) 

(Needs 2] 

(Total direct page space) 



const DPForQuicJsDraw - 5000 

DPForEventMgr - Siofl 

DPForctlHgr - ?40Q 

DPForLlneEdit - 5-S00 

DPForMenuMgr - JSDO 

CPForstdFlie - S70D 

DPForFontMgr - 5800 

DPForPrintHgr - $900 

Totals? - SBOQ 

var tool Ret ; "Too IT able; 

paramBlock : FiVeRec; 
baseOP : integer; 

label 1; (Just for or.co, let's commit the cardinal sin of using the GOTO! I 

b*gln [of startUpTools) 

StartQpToola :- true; (Assume all is well at first) 



TLStartUp; 
CneekToolErrer [SD ; 

MyMemo.ryTD :— MHStartUp; 
HTStartUp; 
CheclcTeo-lError (S2J ; 



(Init Tool Locator ) 



Unit Memory Manager) 
(Init Misc Tools ) 



(Allocate memory space in banK for dlreet-page use by GS Tools:] 

Tool s ZeroPage ; - 

NewHandle [TotalDP, [Allocate memory] 

MyMenvorylD, [Process [user) ID) 

attrBank+attrFlxed+attrLoclted+attrPage, (Attributes) 
Ptr [01]; [Start In ban* D ) 

CheckToolError (S3)? 

baseDP :- LoWord (ToolsZeroPage") ; 



ODStartOp 

(baseDP + DPForQulckDraw, 
ScreenHDde, 
MaxScan, 

MyrtemorylB) ; 
CheckToolError (54); 



(Address of zpag t 3 1 
(640 mode I 

(fiorliontal line slie} 
(Process (user] ID ) 



HP. PAS (main program) 
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EMS-artUp 

(fcasacp + DPForEventKgr, 

2D, 

5, 

MaxX, 

0, 

200, 

KyMemorylD) ; 
Check Too 2 Error ($5) ; 

(Give a message wnile we load RAM based tools:! 



(Address of zpag. 4 4 
$ Event que-qg siZB 
(X mill Ciair.p 
(X max ciair.p 
[Y mtn clamp 
[Y man clamp 
[Process (userl ID 



MtoveTo 
SetBackColer 
SetForeCc^pr 
Drawstring 

ShowCurser; 



Be,20|f 
(0]J 

(15); 

( 'One Moment Please. . . ■ ) ; 



[Now load ram based teals (and 

toolRec.Na.-nToola j- H; 



toolRee. Tocls(l 
tool ROC, Tan ]s[l 
tealRec.Tools[2 
toolRee. Tools [2 
too-lRee.Toolsta 
toolRee. Tools [3 
toolRee. Tool3[4 
too", Rec Tools [1 
toolflec.Too:s[5 
toolHac, Tools [5 
toolHec. Tools [6 
tool He c, Tools [6 
toelHecToolsJT 
toolBec. Tools [7 
toolRee. Tools [8 
tool Re c. Too Is [a 
toolRec,Tools[3 
toolRee, Tools [ 5 



• TSh'um :- 4; 
.MinVarsion 
.TSN-jih :- 5,- 
.MinVerslon 
. TSNun :- 6; 
, Hi n Vers Ion 
.rsifum :- 14 
.MinVerslon 
.tSHum :- is 
.Ml aversion 
.TSNura :- 16 
.MinVerslon 
,TSNum i- IB 
.HijiVersioh 
.TSNum :- 19 
.MinVerslon 
.TENuni :- 20 
.MinVerslon 



toolRee. Tools [ 10 s .TSNum :- 21; 
toolRee. Tools [JQ[ .MinVerslon : 
t D nlRec.Tools[ll] .TSHuiu :- 22; 
toolRec. Tools [11] .MinVerslon : 
toolRec,Tools[12| .TSHunt :- 23; 
toolRee. Tools [12] .MinVerslon : 
toolRao,Toolfi[13] .TSNum :- 21; 
toolRee. Tools [13] .MinVerslon : 
toolRec.Tools[H] ,Tsn™ :- 2S; 
toolRee. Tools [Ifl] .MinVerslon ; 



patches to RM tools!):) 
I QuickDraw II 
( Desk Manager 
(Euent Manager 
(Window Manager 
IKanu Manager 
{Control Manager 
(QuickDraw Aux 
] Print Manager 
(Line Edit 
(Dialog Manager 
'scrap Manager 
[Standard File 
[Font Manager 
[List Manager 



pa ramB lock. pat ft name :- i?" -/SYSTEM/TOOLS" 

GET_FILE_INFQ (parauiSlock) ; 
If toolErr o then 

If MountBootDisJe - 1 then 

goto 1 
else begin 

StartupTools :- false; 
EitU; 
and; 

loadTnoIs (toolHec) ; 

CheekTool Error (Sfcj; 

WlndStartUp (MyMemorylD) ; 

"heckToolError ($7} ; 



(Hake sure tools avail) 



(Load the tools I need! 
Unit Window Manager ) 



416 



Appendix G: Hodgepodge Source Code: Pascal 



RefreshDeskeop (nil) ; 



(Draw the desktop 



I 



ctlstartUp 

(MyMemorylD, 
bsseDP + DFForCtlMgr) ; 
ChcckTool Error ($8) ; 

LEStartUp 

(baseDP * DPForLlneEdit, 
WyKemorylD} ; 
CheckToolError (S9tf 

DialogStartUp 

(KyMeraorylD) ,* 
Che ckTool Error f_5A) ; 

Mer.uSLart.Up 

tWyMenmrylD, 

base DP » DPForMemiMgr) ; 
checkToolError ISB) ; 

DeskStartUp; 
CheckToolError ($c); 

ShowPleaseWaitf 

SFStartOp 

(MyMeniorylD, 

basaD? + DPForStdFlle); 
CheckToolLrror [SD1 ; 
SFAUCaps (true); 

QDAuxStartLip; 
cheefcToolError f$E) ; 
WaitCursor,- 

FMStartlip 

(MyMemorylD, 

baseBP t DPForFontKgr) r 
CtieckToolError (SF); 

ListStartUpf 
CheckToolError (S10) ; 

SctapStartup; 
CheckToolError (511} ; 

PMStartUp 

(MyHemorylD, 

baseDP + DPForPrintMgi") f 
CheckteoIError (S12); 

HidoPlcaseWait; 
Initcursor; 

end; (of Start UpToolst 



[Infc. Control Manager 
[Process (user) ID 
[Address of ipag I 5 



[mlt Line Edit 
(Address of zpa Q I s 
[Process (user! ID 



[Init Dialog Manager 
[Process (user) ID 



Unit Menu Manager 

[Process (user) ID 
| Address of zpaq * 7 



(Init Desk Manager 

(Put up dialog box 

[Init Standard File 
[Process (user) ID 
[Address of zpag t 8 

(1 want filenames In all caps 

Unit QuickDraw Auxll 

(Wristwatch cursor 

(Init Font Manager 
[Process (user] 10 
[Address of ipag I 9 

[Init List Manager 

I Init Scrap Manager 



[Init Print Manager 
{Process (user) ID 
I Address of zpag ♦ 1Q 



(Remove dialog box 
([formal arrow cursor 



HP. PAS (main program) 



AM 



procedure ShutDownTools; 

{Routina to shut down all the tools we used In reverse order of startup. 
Only tools which are currently active are shut down; this facilitates 
recovery from an error condition Irom StartupTools. I 

begin {of ShutDownTools) 

DeskShutDown; 

if Windstatus <> a then 

HideAlIWindows; jClose all windows only if OK! Takes some time 1 

LlstShutDown; 

rMShutDown; 

ScrapShutDown; 

PMS hut Down; 

QDAujiShutDown; 

SfShutDown; 

MenuShutDown; 

DlaiogShutDown; 

LEShutDown; 

ct Is nut Down; 

HlndshutDnwn; 

EMShutDown; 

QDShutQoun; 

MTShutDown; 

if MKStatue <;> then begin 

BisposeHandle {roolaZeroPagej ; [Deallocate tool directpage apace] 
MMShut-Down WyHeirarylD) ; [Do this only If OKI) 

end; 

TLShutDown; 

end; (of ShutDownTools] 



BEGIN (or HAI6T program HodgePodgei 

InitGlobals; ( inltlalze our globals, menus, etc. | 



if startUpToola then begin 
Seti/pDefault; 
SetUpMenus; 

setUpWindows; 
MalnEvent; 
end; 



Initialise IIGS Tools | 
Sec up print dialog | 
Set 'jp menus } 
set up windows \ 
(Tb* application J 



ShutDownTools; ( shut down IIGS Tools ) 

EHD. [of MAIN program Hodgepodge) 
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MENU.PAS (menus) 



CM1T Ke7\u; 






I 



Hodgepodge: An example Apple IIGJ Desktop application 

Written by the Apple IIGS Development Team 
Translated to THL Pascal by TML Systems, Inc. 

Copyright [cl 1986-87 by Apple Computer,. Inc. 
All Rights Reserved 



Paatal UNIT "MENU.PAS" : Xer.u bar setup and menu item handling 



INTERFACE 
•JSEE 



KPIntfPata, 
HPrntfProc, 
HPlntfFdos, 

GloiH Is, 
Dialog, 
Font, 
Faint, 

Window, 
Erint; 



j KodgePodge Apple IIGS Toolbox Interface Units} 



[Hodgepodge Code Units] 



procedure DoMenu; 



{Execute a menu item) 



procedure SetupMenus; I Install menus and redraw ir.er.u bar) 



IMPLEMENTATION 



procedure AddToMenu; 

[ Private routine to add a new window item to the "Windows" menu after a 
new window has been drawn. Increments the variable WIndex, a ccunc of 
the nu*iiber of windows currently open.) 

Var theWindow : Graf Port Ptr; 

myDataHandle : WindDataH; 

begin [of AddToMenul 

theWindow :- Front Window? 

HindowLlst [WIndex) :- theWindow,- 

myo at a Handle :* WindDataH IGetWElefton [theWindow)); 

insertHItem (gmyDataHandlB^-.menuStr [1J r SFFFF,WindowsMenuID) ; 
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It WIndex - then begin (This Lb the first window! 

DttletflMIteBi [NoWindawsIteml; [Remove the "filler" Item) 

SatMenuFlsg (SFFlF.WindowsKenuID) ; (Highlight the menu | 
DrawMenuHar; 
end; 

CalcMenuslze (u,o,wlndowsHenuID) ; 

Inc (WIndex); 
End; (of AddroMejini 

procedure DoOper-.Tterrr 

IPrivate routine which Is called when the "Open..." item from the "File- 
menu OR the "Display Font ■ Item from the "Fonts" menu is selected 

(OpenWlndow will determine which one it was.). If too many windows are 
Already open, then a dialog la displayed.! 

begin [of Doopenlteml 

if WIndex t. LastWir.Q then 

if OpenWindow then 

AddtoMenu 

else 
elsr- 

KanyMl ndD i a 1 og ; 
end; (of DoOpenltem! 



procedure DoQuitltem; 

(Private routine to set Done flag If the "Quit" item was selected) 



begin (of DoQuitltem! 

Done !- true- 
end; (of Doauitltem! 



procedure DoHlndow UtemKum: integer) ; 

[Private routine which brings a specific window to the front of the 
desktop, in response to a selection from the "Windows" menu. ) 

war theWtndow; GrsfFortPtr; 

begin jot DoWlndow! 

theWindow ;- WlndowLlst titenHum - PlrstwlndTtem] ; 

SalectHlndow (thewindgw) ; 

ShawWindow (theWindow) ; 
end; [of PoWindowl 
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procedure ttoMOnu; 

(Erocedure to handle all menu selections. Examines the Event. TaskData 
menu Item ID word from TasKMaster (from Event Manager) and calls the 
appropriate rnutine. While the routine Is running the menu title is 
•till highlighted. Alter the routine returns, He unhilight the 
menu title.} 



var xenuNuni 
it«TlNUm 



Integer; 
Integer: 



begin (of DoMenuj 



menuNum 
ItemNum 



HiWord (Event , waTaskData) ; 
LOHord (Event , WT.TasliData) ; 



case ItemNum of 

Aboutltem 

Openltejc 

CloseK em 

SavoAsItem 

ChooseFTtem 

Page Set Item 

Erintltem 

Quit Item 

Undoltem 

Cutltcn 

CopyTtem 

Pasteltem 

Clear: Lex 

Font Item 

Mans It em 
otherwise 

poHindny tltercNum) ; 
end; 



Do About Item; 

DaOpenltem; 

DoCloseltero; 

Dosaveltear; 

DoChooserlcera; 

Qo5etupItem; 

DoPrintltern; 

DoOuitltem; 



DoCpenitem; 
DosetHono; 



HliiteMenu (false ,ir.e nuNuu} ; 
ena f (of CoMenu] 



(Unhlghilght the menu title! 



procedure SetUpHenus; 

[Procedure to install our menu titles and their Items in the system menu 
bar and to redraw It so ve can sea then),) 



var height ; integer; 

begin (of SetUpMenusl 
setHTltieStart (10); 



(Set Starting position of menu! 



InserLMenu {NewMemi (SFontMenuStr [1]> 

Insert Menu (NewManu [UWlndoWMenuStr [1]} 

InsertHenu (NewMenu (BEditMenuStr [1]1 

InsertMenu (NewKenu (IPlleManustr Jl] y 

insertMenu [NewMenu [SAppleMenuStr [1]} 



• Oil 


( Fonts Menu 1 


,0); 


[Window Menu ! 


. : i ; 


(Edit Menu | 


,0); 


(File Menu 1 


,01; 


(Apple Menu I 



FlxAppleKenu (AppleMenuID) ; 
height :- FixMenuBar; 
CrawHenuSar; 
end; (of SetUpMenusj 



(Add DAe to apple nervj ] 

(Set sizes of menus ] 

(...and dra*» the menu bar!] 



DO. 
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EVENT.PAS (main event loop) 

UNIT EVsnt; 



Hodgepodge; An example Apple TICS DesKtop application 

Written by the Apple lies Development ream 
Translated to TML Pascal by TML systems. Inc. 

Copyright (c) 1986-87 by Apple Ceinputer, Inc. 
All Rights Reserved 



Pascal UNIT -EVENT.PAS" : Event loop and dispatching routine 



INTERFACE 
USES 



KPIntfData, (Hodgepodge Apple HGS Toolbon Interface Units! 

HPIntfProe, 

UPIntfPdos, 

Global s, [Hodgepodge Code Units} 

Dialog, 

Font, 
Paint, 

Print, 
Menu; 



procedure MalnEvent; (Main event handling loop which repeats until Quit! 



IMPLEMENTATION 



procedure MainEvent; 

(Hain event handling routine which loops until the Done flag Is set by 

select!™ of the "Quit- item. We call the window Manager's TaskMaater 
routine, which calls the Event Manager's GatNe*tEvect routine and 
handles window resize tracking/resizing, window movement tracXing/resUlng, 
window activlitlon (bringing to front by clicking on an Inactive window], 
among other things. TaskMaster returns control to us when the user has 
clicked a window's GoAway check cox, or when the user has selected a menu 
Item, either with the mouse or with an equivalent Solid-Apple keystroke 
sequence. ] 

var code : integer; 
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procedure CheckFrontW; 

[Check to whom the front window belomjs to (us or a Desk Accessory (CA) ) , 
and If It belongs to us, whether it is appropriate to disable (dim) certain 
menu items [such as the Save item) or to enable than. Private routine, \ 

var theWindow. : GrafEortFtrs 

myDat a Handle ; WindDataH; 



procedure Disable It ems; 

[Private routine to disable [dim) certain menu titles] 

begin (of Disabl el terns} 

DlsableKltem (SaveAsItera) ; 

DlsableMItem {Close It em] ; 

DlsableMItem {Prlntjteir,] ; 

D 1 sableMlt am [ PageS et I tern} ; 
end; [of Dlsableltems ) 






procedure Enableltems; 

[Private routine to enable (undlm) certain menu titles! 

begin [of Enableitans) 

EnableMItem (SaveAsIten) ; 

EnsbieMJtEra (Closeltem) ; 

EnableMItem jErlntlteml; 

Enalo 1 eKItera (Pageset I tern ) f 
end; (of Enableltems! 



procedure D 1 sabl e Al 1 ; 

(Private routine to disable all menu titles Tor Desk Accessory (DA) i 

begin [of DlsableAll) 

SetMenuFlag ($<JDB0, EdltNenuID) ; 

DrawMenuBar; 

Disablements; 
end; [of DlsableAll I 
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procedure SettlpForAppW, 
[Called if a 



Pri™,^i£?f Catt *° "***" ( ™ S) lB the fr -^ "l«*». 



begin |of SetUpFarAppW] 

SetMenuFlag (50DB0, EflltMenulE] ■ 

DrawMenuBar; 

Enable It ama; 
end; | of SetUpForAppW| 



procedure SetUpFotDAW; 

^lle d if , Desk *™.„ y . s wlndotf 1E ch# frentmost ^^ privato ^ 

teffin [nf SecUpFoiDAV) 

Disablertecis; 
EnableMItem (Closeltem}; 
SetMenuFlag [SFF7F, EdltMenuID) ■ 
DrawHenuBar; 
end; j D f Sett/pForDAWJ 



begin (of Check Frontwj 

thewindow :- FrontWindow; 

if theWlndow - last Window then 
Exit»- 

11 thawindow - n ll then 

ClaitaleAll 
else begin 

If GetsyaWFlag (th.wlndow) - true than 

SetUpforDAw 
else begin 

SetDpforAppW; 

KK^i^K 6 ^ T h T Kon (th — • •• 

DisableHltem (Sav E AsIten) 
era; 
end; 

lastWlndQw ;- theWindow; 
ffill f fot Check FrontW} 



begin f„f MainEvetit] 

Event.wmTaskMaa): r- SDDMiFPr. j»n 

Done _ f°,„ FFF ' !AUow Taskmaster to do everything! 

repeat 

Check FrontW; 

code :- TaskHaater (SFFET, Event > - 

case cckJb of 

wlnGoAitfay ; DoCloseltem; 
winSpecial, 

wlnMenuflax : DaMenu; 
end; 
until Done; 
end ; (of MainEventJ 



m *T — >-« lo tto everything] 

(Do ne flag wln be aeC h y Quit Uc»> 



END. 
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WINDOW.PAS (windows) 



m 



T Hlr.dou; 



Hodgepodge; An example Apple I IGS Desktop application 

Written by the Apple I IGS Development Team 
Translated to TML Pascal by TML Systems, Inc. 

Copyright (t) 19BS-B7 by Apple Computer, Inc. 
All Rights Reserved 



Pascal UNIT "WINDOW.PAS- : Routines to open and close windows 



-■I 



:n:lS;«:- 



l-SES 



HJIntfData, 
HElntf Proe, 
HPIntfFdos, 

Globals, 
Dialog, 
Paint, 
Font ; 



'Hodgepodge Apple IIOS Toolbois Interface Units! 



I Hodge Radge Code Units) 



procedure DoCloseltem? 
procedure HideAiiwindows; 
rune lor □tietiHlndow : boolean; 
procedure Setupwlndows; 



[Closes current frontmost windov t 

[closes all windows on the desktop 
(Tries to open a font or picture window ) 
(initialize variables for stacking windows! 



IMP'-EMENTATIQK 






Biywlnd 


: Parajntist; 


wXoffset 


: Integer; 


wYoffset 


: integer; 


iSIsPos 


: Reet; 



procedure DoCloseltem; 

{This procedure closes the frontmost window and deallocates all of Its 
associated storage. NDA windows are supported for when this procedure 
Is called by HideAll Windows when enitting Hodgepodge. f 

var theWLndow : GrafPortPtr; 
myDataHandle : WindDataH; 
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procedure AdJWlnd (theWlndow: GrafPcrtFtr] % 

\ Finds the window designated by theHindow and removes it from the 

WlndowList and returns the position In the window list where It was 
found. Private function. | 

var i : integer; 
theOne : integer; 

begin |of AdjWlnd| 

(Find the inde* of the grafportptr of the window being deleted- 1 

1 :- firscwlnd; 

while windowLlat (1] <> theWlndow do 

Inc (1); 
theQne :- i; 

I Remove corresponding item from the HINDOK-nnnu- | 

if windax - 1 then beotn (LaEt window-special case} 

InsertMltem (GNoWindstr [1| .FlrstWlndlte*, + theOne,WIndows>fenuID! • 

SetMenuFlag [fDOSCWindowsHenull]); 

DrawKenuBar; 

wXoffsat :- 20; 

wYoffset :- 12; 
end; 

DeleteMItem (Flrstwindltm + theOneJ; 
CalcMtnuSize [0, 0,windowsM«nuID) ; 

inc y a" Uy ^^^ (SCro11 ' the flrafportptr of the m-£ated window:! 
while 1 < LastWlnd do begin 

WlndowLiist [1 - l] :- windouiUt 111; 

Inc (1); 
end; 

[Renumber the WINDCW-memj It ana:] 
for 1 :- theCne to LastWlnd do 

SetMltemlD (FlrstWindltenH-1-1 {new ID) , Flr S tWlndlte m *I [old n»); 
end; |of Ad]Wlnd| 

becin (of DoCloseltem} 

theWlndow ;- FrontWindow; 
cioaeMDAbyWinPtr (theWlndow} ; 
If isToolError then begin 



(theWlndow) ; 

!- WindDataH [GetWRefcon 

(Handle (myDataHandle) ! ; 

(theWlndow) ; 

(Wlndeji) t 



\lt wasn't an NDfl window) 
(Update WINDOW menu] 
(theWlndow)] ; 
[Deallocate stcrage| 
[Hemova the window} 
linden Into window Hat} 



Adjwind 

myDataHandle 
OisposeHandle 
Closewlndow 
Dec 

end; 
<=r.d; i of Doclosalteml 

procedure HideAll Windows; 

'Ef^rlr* V, 1 Do ^ lo3eItem « ci0 ^ the frcntmost window ( tf hlch has the 

tUTiJ t " th " "** d8eper laVEl " lrd0 " the **«mt»it one) until 
there is no frontmost window anymore; ie, there are no mare windows.} 

begin (of HldeAllWlndews] 

while FrontWindow <> nil do 
DoCleseltera; 
end; [of HideAllWindoHs} 
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notion opanwindcw ; Boolean,' 

ITries to open either £ font or picture window, depending on the 
Event, TaskData returned from TasXMaSter (which got it from LITE 
Ever.t Manager!. True/false is returned depending on whether a 
window was actually opened. Note the way in which the different 
functions are called in the if-then-elsa structure below. Each 
function tries to do what Its name Implies, and the true/false 
result that each returns la used to determine if the ne*t logical 
function should be called.) 



function DoTheQpen: boolean; 

[this function tries to open a window and returns true/false depending on 
its success. ] 



var t he-Window 
myOataHandle 
theMenuStr 
ourFontlnfo 



GrsfPOrtPtrj 

WlndDataH; 

Str255; 

Font in f org cord; 



begin {of DoTheOpen) 
DoTheOpen j- false; 

HiyDataHandle :- WlndDataH WewHandle (slzeof (WindDataRecl , 

MyHemorylD, 

attrLocked + attrFixed, 
Ptr (OMt; 

if isTool Error then 
Exit) 

with nywlr.d do begin 



pa ramie ngth 


- 


slxeof (ParamLlst! ; 


wFrameBits 


- 


SDDAO; 


wRef-Con 


- 


longint InyDat aHandle) ; 


SetReOt 


(wZoom,{},2S,fr2D ( lS 


wColor 


- 


ni 1; 


WYOrigln 


- 


0; 


wXOrigir. 


» 


0; 


wDataH 


- 


188; 


uDataw 


- 


S4Q; 


wKaxK 


- 


200; 


wHaxW 


- 


640; 


user c-llver 


- 


it 


wScrollHor 


- 


16; 


wPageVer 


- 


40; 


WPageHor 


- 


160; 


wlnfoRefeor. 


. 


Q; 


wlnfoHsighl 


- 


°? 


wFraroaDef Proe 


- 


nil; 


wlnfoDefProc 


- 


nil; 


wPlane 


- 


-1; 


w Storage 


- 


nil; 


end? 






thaHenustr s- com 


-a 


: {>--■, 



myReply, filename, 

IntTc-string iFirstwindlteni + windex), 
no.'}; 



with rayDataHandle A " do begin 



Nair.e 
MenuStr 
Hen u ID 



end; 



- myReply. filename; 

- thaHenustr; 

- FirstHlndlteni + Windex; 
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if Loword (Evefit.wmTaskData) - Font It em then begin 
I We're opening a font window:' 
myHlnd.wContPEtPrnc :- SDispFontWindow; 
with iriyoataHandle*" do begin 

flag :- 1; 

theFont :- Den 1 redFont ; 

IsMono ;- IsMonoFont; 
end; 

TTisLalLFant (BestredFont ,a| ; 
Get Font Info {ourFont Info} ; 
HyWlnd.wDataH :- 15 (KumLines+2J * 

(QurFent Info .ascent + DjrFontlntD.descefit) ," 
[Call to a FindMaxWldth procedure would be placed here to eet 
the MyWlnd.wDaLaW field to length of the longest line of text.] 
End eiss begin 

(We're opening; a picture window;! 
myWind.wContDef Proc :« SPaint; 
with [nyDataHa^«ile J " , do begin 

flag f 0; 

pict :- pietHndl; 
end,' 
end; 

with myWlnd do begin 

wTltle :- *iuyDataHanille**.Najiief 

Set Rent (wPos 1 t t on, wXoffaet + iSilPOS.hl, 

w¥offset + islz.fos.vl, 

wXoffset + iSiiPos.fr;!, 

wYoffset + iSliPos.vS); 
end; 

wXoffset :- wxoffsat +■ 20; {Update globals which offset new window pos | 
wYoffset :- wfoffset + 12; 

If wyoffset > 120 then (Cause stacking effect | 

wYoffset :- 12; 

(How create the window;] 

thaWindow :- NewWlndow (uiyWlndl; 

Sac Port (UieWindow) ,- 

SeLQrlginMask (SFFFE,thoWindow| ; 

InltCursor; {Go bade to the arrow cursor) 

DoTreOpen :- true; (Indicate successful completion! 

end; iof DoTheqpenl 

begin iof OpenWindow | 
OpenWindow ;- false; 

If LoWord (Event .wmTaskDa La) = Font It em then begin 
If DoChoesoFont then 
If DoTheCpen then 

OpenWindow :» true 
end else begin 

If AskUser then 

it DoTheOpen then 

OpenWindow :- true 
end; 
end; (of qpenwindaw] 

procedure setupHir.dDws; 

bEtjLn (of SetUpWindowsf 

wXoffsot ;- 20; [Initial window position offset used for) 

wYafrset :- 12; [...sticking the windows.) 

SetRect (iSliPos,10,2D,350, BOj ; 

a nd ; ( of Set UpWi ndowa [ 

F.ND. 
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DIALOG. PAS (dialog boxes) 



WIT Oislug; 



HodgePadge: An example Apple IIGS Desktop application 

Written by the Apple IIGS Development Team. 
Translated to TM1 Pascal by TML Systems, Inc. 

Copyright [c) 1936-87 by Apple Coirputer, Inc. 
All flights Reserved 



Pascal UNIT "DIALOG. PAS " : Dialog and Alert box drawing routines 



-i) 



aiTERFaGE 



iSES 



HPir.tfGat 1, 
HPIntfPrDc, 
HPIntfPdos, 

Global s; 



( HodgePodge Apple IIGS Toolbon Interface Units! 



| HodgePndge Code Unit] 



current I tern I : ItemTeroplate,- 

current I tem2 ; itanTemplste; 

orlgEort : GraiPertPtr, - 

tisgwindptr : GrafPortPtr; 



procedure DoAboutltsis; 

sroeedure ShcwPleaseWalt; 

procedure Hide? lea sen a it; 

function ChecltDlskError (Where : integer) 

irocedurB ChecklrjolError (Where : integer) ; 

function Mount Boot Disk ; Integer; 

procedure KanyWlndDlalcg; 



(About it an in apple nenu 
IPlease Walt during inlt 
{Erase the above 
boolean; I Alert it FrnDOS error 
(Death If tool error 
(AsJt boot disk; 1 if OR 
(waits until OK clicked 
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IMPLEMENTATION 

procedure HaJteATemplate (Theremplate : AlertTempPtr; TheStr : StrlngPtrj; 

( Private routine which creates An alert tsaplate. ! 

begin (or MakeATemplate! 

with TheTamplate" do begin 

StscReet (atBoundsRect, 120, 30,520,80) | 



15DQ; 

- 580; 

- SSQ; 

- *H0; 

- 5B0; 

- Scurrentlteml; 

- d current It. em2; 

- nil; 



■tAlsrtJC 

acstagel 

at stages 

a.tstage4 

at I toad 

atltenS 

atltemS 
end; 
wtth current I tenil do begin 

Itomld :- l; 

SetRect (ItemHact,3Za,^5,0,Dj; 

itemType s- 10; (Butttnn Item constant >l<) 

ItemDescr :- 8'OK"; 

ItemUalue ;- 0; 

ItemFlag ■» 0; 

ItemColor z* nil; 
end; 
with current I tem2 do begin 

Itemld] ■- 2; 

SetRect (ItamHecrt,"J!,ll, 639, 199) f 

ItemType : , 15 + SBQOO; (Disabled Static Text It am constant >!<) 

ItemDeacr :- Pointer {The£tr>; 

itemValue :- 0; 

IteraFlag :- G; 

ItemColor :- nll; 
er.d; 
end; (of MaleeArempLate) 

procedure Show p lea seWalt; 

[Displays "Please talt...- dialog bo* on the screen.] 
var r : race; 

begin (of ShowPleaseWalt ] 
origport :- Get Port; 

manWindPtr :- GetNevHodalDialog (SPlaWtTemp) ; 
SetSeet fr, 70, 19, 640, SAD}; 

NewDIten, (msgwlndPtr.lSDZ, r, IS, a-Please wait while we set thing* up ' 

DjQrEolnteriO]) ; 

BeglnUpdate (msgWlndPtr) ; 

nrawDialog (nsgHlndFtr) ,- 

Endirpdat e (msgWi ndp t z} : 

end; (of ShowPleaseWalt J 

procedure H ide Pleas eWait; 

I Removes -Please Wait...- dialog box from the acreen.l 

begin jot HldePleaseWalt I 

CloseDialog (losgWindPtr) ; 
SatPort (orlgport) ; 
end; [of HidePleaseHait} 
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function CheekDlskError (Where : integer) : boolean; 



[This routine checks if the last. ProDOS operation caused an error. If so, 
then we change the cursor to the arrow cursor, put op a atop alert 
dialog, box with the text of the error message, change the cursor back to 
the wristwatch, and return TRUE as the function result. IE there was no 
disk error, then we simply return with FALSE. f 



var I K emC 1 1 erked 

ourftlert 

ourErrStr 

□urwherestr 

ourstring 

diskr.rrN.um 



integer; 

MertTemplate; 

str255; 

str255; 

str?55; 

integer; 



begln |of CheckDiskErrorl 

diskErrNum {- tool Err; (Use the std C-l 

cheekDlskErrcr :- (diskErrNum <:> 01; 

ourErrStr :- 'XXXX'; 

ourWhereStr :- 'XX'; 

if dlekErrMum <> then begin 

(**' If desired, get disk err string here] 

IntJHex (diskErrNum, 

StringPtr (lnnglnt (SourErrStr) + 

*u 

lnt2Hex (Where, 

StringPtr (longlnt (fourWhereStr) 

Z); 
ourString :— concat ("Disk Error 5', 

ourErrStr, 

" occurred at $" r 

ourWhereStr, 

' - ' I i 
KakeATemplate (GourAlert, PourString) ; 
I nit Cursor ; 

itomclicked :- StopAlert (eou,rAlert,nllj j 
(Do not restore watch cursor \ 



Ike toolerr var for P/161 

[Assign function result) 
I Set string length byte! 
(Set string length byte! 



1), 

(Set ASCII error * str I 



+ l», 

(Get ASCII where t str \ 
(Build our error mesg \ 



[Build our alert troplt J 
[Sat arrow cursor ] 

(Draw dialog t wait I 



and,' 



end; 



(of CheekDiskError] 









procedure ManyWindBialog? 

(Displays alert dialog (triangle with "!") with a message about no more 
windows being allowed open, Handles mouse events until the OK button 
Is clicked. Then the dialog box Is removed and we return. i 

var ourAlert ; Alert tempi ate; 

ourScrlng : Btr255; 
ltemclickad : integer; 

begin {of ManyWlndDialog) 

oprstrlr.g j- "No more windows, please.'; 

MakeATenplate (SourAlert, PourSt ring) ; 

ItemClicked :- CautlonAlert (6ourAlert,nlll ; 
end; [of ManyWlndDialog] 
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procedure Cheek Tool Error (where ; integer!; 

{This routine er-.ecks If the last tool called returned an error code. 
If not, then wo just return. Else, we exit to the system death 
handler routine which prints our string showing whore we bombed. The 
death manager adds the tool error ende to the end of the string, and 
puts the bouncing apple on the screen.] 

var toalErrorsaue s Integer; 

doathMsg : string; 

begin (of CheckToolEiTor] 

toolErrerSave :- ToolErrorNum; 

deathMsg :- ■ At SHOW; Could not handle error S',- 

If toolErrorSave <> than begin 

(Add the hex^in-asell number to the strings I 

Int2Hex [Where, StringPtr Uonglnt (^deathMsg) +6) , 4) ; 

[Malt with our death message string and tool error code:} 
SysFailMgr |toolErrorsave,deathHsq) - 

end; 
end; [of CheckToelErrorl 



function Mount Boot Disk : integer; 

var 

promptstr : string; 

oltstr : string; 

cancelstr : string; 



VOlStr :: String; 

gbvParama : PatnNaineRec,- 

begin [of MountBootDisk] 



pramptStr 

okStj- 

caccelStr 



■Please insert the disk'; 
■ OK ' ; 

■Shut Down"; 



ghvparams. pathname :- a«olstr; 

get_BQ0T_VOL | gbvP a rara s ) ; 

MountBootDisk :- TIMnuntVoliime ( 174, 30, promptstr, vol St r, ok Stir, cancel St r) ; 
end; (of MountBootDisk \ 



procedure DoAboutltem; 

var aboutDlog s GrgfPortPtr; 

r : Beet; 

itesiiHlt ; integer; 

applelconP ; Ptr; 

applelconH : Handle; 

begin (of DoAboutltem] 

(Draw the dialog box on the screen: I 
SetRect (r, 146, 20, 495,192); 

aboutDlog :- NewModalDlalog (r, true, 0); 

[Add an QK button to lt:| 
SetRert. (r, 270,153,0,0); 

ItewDIcepi [aboutDlog, l,r, Butt onltem, S "OK", 0,0, nil) ; 

(Add the Apple logo to it: I 
setRect (r, 20,135,0,0); 

applelconP :- PApplelcan; 
applelconH ;- SapplelconP; 
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NeuDltem (abouLDlog,3, r, loonltem * ItemDisable, appleleonH, 0,0, nil) ,* 



[Simply 



write the text rather than create a hunch of dialog Items: I 



Set Part. (about Dlog) ; 

setForeCclor (0) ; 

SELBAckColPC (15) 1 

WoveTo (40,171 ; 

setTextFaee <BI; 

Drawstring C Hodgepodge'); 

SetrextFace (0! ; 

MoveTo {40, 27); 

Drawstring (■ A potpourri of routines that'); 

Hotfelo (40,37); 

Drawstring (■ demonstrate many features of'),' 

MoveTa (40,47); 

DrawStrlng (' the Apple IIGS Toole, 'I; 

KoveTo (40,67); 

Drawstring C By the Apple IIGS Development Team'); 

HoveTo (36,77); 

Drawstring ('Translated to TML pascal by TML Systems' ); 

MOVGTQ (40,87); 

DrawStrlng [* copyright Apple Computer, Inc.'); 

MoveTo (4D,117>; 

DrawStrlng C 1986-87, All rights reserved- ); 

HoveTo (40,127); 

Drawstring (' "4,0 23-Sep-97'>; 

(Let Dialog Manager handle all events until the OK button Is cllckEd: | 
ItemHlt :- ModalDialog (nil); 



end 



(Remove the dialog box from the screen:] 

CloaeDlalog (aboutDlog) ; 
(of Do About Item) 



END. 
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FONT. PAS (fonts) 



UNIT Font; 



Hodgepodge: An example Apple JIGS Desktop application 

Written by the Apple IIGS Development Team 
Translated to TNI Pascal by TML Systems, Inc. 

Copyright (cj 1S8 6-B7 by Apple Computer, Inc. 
All Rights He served 



Pascal UNIT "FOtfT.PAs" ; Font window drawing routines 



-+l 



INTERFACE 

uses 



HPlntfData, (Hodgepodge Apple lies Toolbox Interface Units] 

HPIntfProc, 

Hflntfpdos, 

Global*; (Hodgepodge Code unit} 



procedure uispFontWindow; (Draw fn6t wln6ov CDntents . 

function EoChooseFont: boolean; [Dialog for asking font size, etc. I 

procedure DoSetMono- r^.f. *n -i -t ■*">, kc ' ' 

r,™™,, , iT™ . [seta flag md arfects menu item ( 

procedure Sho«Fcnt (theFontID: FontID; isHono: boolean); (Actually draw font) 



IMPLEMENTATION 



procedure ElspFontwlndow; 

<Thia Is a Definition Procedure used to dray the contents of a Font 
window. J 

var tjcpPort : GrafPortPtr; 

myDataHandle : wlndDataH; 

begin (of DispFont Window J 

tmpPort :- GetPort; 

myDataKandle ;- WindDataH (GetWHefCon (tjhpportu; 

with myDat a Handle" do 

ShowFont (thsFont, IsMono) ; 
end; (of DispFontWindow) 
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function EoChooseFonts boolean; 

(Display the Font Manager's dialog, for the user to select a font, 
font size, and font style. 

The function returns tr-ie !f a font was chosen, else false If the Cancel 
button is pressed In the dialog. If a font Is chosen, its FontTD information 
Is returned in the global variable Desir adFont . In addition, the 
global myReply . f 1 lenaxe contains a string which is the font's file naine. 

Because the call to ChooseFant actually changes the font of the current 
port, vie must first save the current port and open a dummy one do that 
our current port Is not affected,] 

var theFont : Font ID; 

dUMfty ! Integer; 

tir.pPort i GrafPortPtr; 

tjr.pPortRec ; GrafEort; 

fairName : Str2S5; 

begin (of DoChooseFont) 
tuipPart :- Getport; 
OpenPcrt [8trnpFc.rtp.ec]; [save currant port and open new one] 

theFont :- ChoosaFont (DeslredFont, Q) ; (Do standard dialog box] 

if longint {theFont) - then {Cancel was chosen) 

DoChooseFont :- false 
else begin 

DealredFont :- theFont; (Update global DeslredFont f 

dummy :*■ GetFamlnfo (DeslredFont.fantNujn, famNane> ; 
nyRcply. filename :- 
con cat (famMame, 
■ i 

I ntTaSt r 1 ng (Des 1 redFont , font Size}),* 
DqChDoseFont ;- true? 
end; 

cl ose Port ii tmpport Rec ) ; 

SetPort [tmpPort) $ (Restore current port! 

end; (of DoChooseFont) 



procedure DoSetKono; 

[This procedure flips the flag indicating whether we are currently 
displaying a font In mono- spacing or not, and updates the 
font menu item accordingly, f 

begin [of toSethbno ) 

If IsMonoFont then 

EotMItera (MonoStr,HonoIteml 
else 

SetMItem (PToStr,MonoIteni> ; 
IsMonoFont :- not IsMonoFont; 
end; [of DoSetHonol 
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procedure ShoWFont UheFontXD: FentID; isMono: boolean) ; 

var font Info : FontinfoReeord.; 

carrHelght : Integer; 

1, j : Integer; 

thech : integer; 

carrPt 3 Faint; 

fontSLr : Str2S5 r - 

begin (of ShowFont ) 

InstallFont [theFontID,Q> ; 

GetFantln^o (fontlnfo) ; 

currhelght ;- fontlnfo, ascent + fontlnfo .descent + fontlnfo, leading; 

1 :- Get Faro In ro (theFontlD.famNuni, fontStr) ; 

fontstr !- conoat (fcntstr, ' ', IntTaStrihg (theFontlD. ContSIie)) j 

i :- GetFaqt Flags; 
If isMono than 

1 :- Hi tor (1,S0001) (Set bottom bit] 

el*e 

1 :- Bit And [i,S!000); (Clear bottom bit ) 

SetFontFlagsll) ; 

MoueTo 1 5 , cur r He 1 g ht ) ; 

Drawstring (fontstr); 

MosieTo (5, citrrHaight * 3) ; 

Drawstring ! 'The quick brown fox jumps over the lazy dog. ' 1 ; 

MoveTo (5, currHeight * 4) ; 

Drawstring. (-She sens sea shells down by the sea shore.'); 

MDveTo |5, currHeight ■ 5> j 

for i !- tfl 7 do begin 
Get Fait (eurrFt}; 

MoveTo (5,currPt.v + currHeight); 
theCh :- 1 • 3?; 
for j ;- l to 32 do begin 

fontStr (j] :- cfir (theCb) ; 
inc (thech) f 
end; 

fontstr [0] :- chr (32); 
DrawStrlng ( fontstr); 
end; 
end; (of ShowFont I 
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PRINT.PAS (printing) 



UNIT Print; 






Hodge?adge; An example Apple 1IGS Desktop application 

Written by the Apple lies Development Team 
Translated to TML Pascal by TML Systems, Inc. 

Copyright (c) 1986-87 by Apple Coirputer, Inc. 
All Slights Reserved 



Pascal UNIT -PRINT. PAS" : Window content printing routines 



INTERFACE 






USES 



HP I nt IDat a, 
HPInttProc, 
HPIntfPdos, 



[Hodgepodge Apple IIGS Toolbox Interlace units) 



Globals, 
Dialog, 
Font, 
Paint f 



{Hodgepodge Cede Units) 



procedure DoChooBerltemf 
procedure DoSetupItem; 
procedure Dc-Printlteni; 
procedure Set UpDefault; 



[Show atandatd chooser dialog to select options) 
[Show standard page setup dialog to sel options) 
[Print contents of current vrlndow to printer ) 
(Create and Initialize THPrint record ) 



lKPLZMENTATION 



war prinlKndl; 



PrRecHndl; (Private print record handle for Print Manager] 



procedure Dochooserltem; 

(Display the Chooser Dialog for the user to select which printer and 
printer connection to use,} 

vir dummy: boolean; 

begin (of poChOOSerltern;' 
dummy :■ PrChooser; 

end; (of Dochooseritem) 
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procedure DoPrlntltem; 

(Print the contents of the ficont window to the selected printer.} 

var prport ; GrafPortPtr; 

thewlndow s GrafPortPtr; 

procedure DranropWindcw (thewindow: Graf Port Ft r I ; 

^ll/tir^^^f F* detennln * s **»t type of window theNindow l s a„d 
ca Us the appropriate procedure to draw It* contents to the current port 
which Is now the printer port created in BoPrintltera. 1 

var myDataHandle; VflndDataH; 

begin (of DxawTcpWlndokrl 

myDataHandle :- WindDataH [CetWRefton (theWindow) ) , 
with p^yDa^.aHandle'■' , do 
if Flag - o then 

Paint It (plct) 
el 7.c. 

shnwFont (t hofo nt , l sMo no ) ; 
end,- | of DrawTopwindowl 

begin (of DoPrintIte:i!| 

theWIndow :- Front Window; 
if theWIndow <> nil then 

If PrJobOialog (printHndl) then begin 
WaitCursor; 

prPort j- PrOpenBoc (printHndl, nil ) ; 
PfOpenPage (prPort, nil ) ; 

DrawTopwlndow (theWIndow) , 

PrClosePage IprPortJ ; 

PrcloseDoc (prPortl ; 

PrPicFlle (printHndl, nil, nil) ; 

in it Cursor; 
end; 
end; [of DoFrintltem) 

procedure DoSetupltem; 

'ssssvrtsr s^rs? the user to *— ^ -** — . 

var dumny: boolean; 

begin |of Dosetupltem] 

dummy t- PrStlDialoo (printHndl); 
■nd; (of DnSetupItemt 

procedure SetUpDefault; 

f £V*T '** lnitia "* & * ™Frint record which I, required for all 
printing operational H " 

begin (of SetUpDefault f 

printHndl :- PrReeHndl (NewHandle (iflD, 
inyMejnorylD, 

attrNocross + attrlocked, 
Ptr (0|M; 
PrDefault (printHndl], ; 
end; (of SetUpDefault | 



EJJD, 
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I 



PAINT.PAS (pictures and files) 



UNIT Paint; 
(+ — — 



HodgePodge; An example Apple lies Desktop application 

Written by the Apple lies Development Team 
Translated to TML Pascal by TML Systems, Inc. 

Copyright [*1 19B6-B7 by Apple Computer, Inc. 
All Rights Reserved. 



Pascal UNIT "PAINT, FAS" : Bitmapped picture load/ save and window drawing 



-■I 



INTERFACE 



HPIntlTJata, 
HPIntf Proe, 
HPIrttfPdcE, 

Globals, 
Dialog,- 



( Hodgepodge Apple TICS Toolbo* Interface Units | 



(Hodgepodge code Units! 



function Asktlser : boolean; (load a new picture Irom disk! 

procedure DoSavelten," (If paint window in front, do Std File dialog i sane! 

procedure Paint; (Draw picture window contents! 

procedure Paint It (plots Handle); (Do Paint's dirty work] 



IMPLEMENTATION 



(SDefproc ! 

function OpenFllter (DirEntry : longlntl 



Integer; 



[Filter function called by the Standard File Operations" SFGetFile 
dialog to determine wine* her a filename should be dimmed or not.| 



type 

BytePtr ■ *byte; 
var 

flleTypePtr : BytePtr; 

bEgln (of QpanFilter} 

fileTypePtr :~ Pointer (DirEntry * 510); 

if (EltAKD(FlleTypePtr-,$DOFF) - $C1) then ( Unpacked Picture File type ! 

OpenFllter :- 2 
else 

OpenFllter !- 1; 
end; (of OpenFllter) 
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function AsfcUsejf : boolean; 

var ourrypeLiat : rypelistPtr; 

function LeadOne : boolean; 

I Private procedure which actually loads ■ picture from disk] 

var openBlk : OpenRee; 
readBis : FilalOftoc; 

begin [of LoadDne) 
LoadCne :- false,- 

WaitCuraor; 

PlctHndl :- ISewHandle (SBQOQ, 

KyMemnrytD, 

Oj 

Ptr (0)); 
if leToolError than 
Exit; 

HLock (PlctHndl > ; 

opBii&lJt.npenPathrjame :- SmyReply . fullpathname; 
openBlk.ieBuffar :- nil; 

OPEN (openBlk); 
If ChackDisfc Error (27) then 
Exit; 



readBlk , dataBu T( er 

readBlk.rEqoestcount 
readBlk.fHeKefNum 
READ (readBlk); 
if CheckDlskError (28) than 
Exlt; 

CLOSE (raadBllO ; 
HnnLock (PlctHndl ) ; 

LoadOne :- truej 
end; (of LoadOna] 



begin (of AskUser) 

SFGetPHe (20, 

■Load which picture!', 

SOpenFllter, 

NIL, 

Kyftepiy) ; 

AskUser :- false; 

If iryReply.g/ood Chen 
If LoadOne then 

AskUser |« true; 
end; (of AskUser) 



- PictHhdl*; 

- SBQ0D; 

- openfllfc.qpenftefNmri; 
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procedure Dosavelteisi; 



[This procure is called to w the contentB of * ■'Paint- window 
to a disk file. NOTES Thia routine is ONLY called when a -Paint" 
wlndnw Ls In front due to enabling/disabling the menu items. | 



var theWlndow: GrafPcrt Ptr; 

myDataHandle: WlndDataH; 
1: integer; 



procedure saveOne (pict : Handle) ; 

[Private procedure which actually does the picture save] 



var dastroyBllt 

ex eat eB Ik 
open Bl It 
wrlte-Blk 



PathNameRec; 
File Reef 
QpanRec? 
FlIeloRecr 



begin (of SaveOne] 

destroyBlk, pathname :■ 
DESTROY {deatroyBlM; 



createBllt. pathname 

ere at eBl It. f Access ;- SC3; 

createBllt. filEType :- 5C1; 

createBlk.aUJtType :- 0} 

createBllt. EtorageType :- 1; 

createBlk.createDate :- Of 

createBllt, createlime !« 0; 
CREATE IcreateBlk) I 
If ChockOiaKError (25) then 
Exit; 



BmyRaply . fullpatfiname; 



- Gtfiy Reply, full pathname; 



(DRbWR, see ProDOSl6 docs J 
[Dnpaclted file) 
(-nothing-! 
(Seedling [1UI 



openBlk.openPathname :■ 
DpenBllt.laBuffer :■ 

OPEN (epenBllt); 



(JmyReply. iullpathname; 
nil; 



wrlteBlk.dataBuffar 
wrlteBlk, request Count 
wrtteBilt ,t HeReiNim 
WRITE (wrltealkl; 
If ChecleDUJtError (2e> then 
Exit; 

CLOSE (wrlteBlk}; 
and; [of SaveQneJ 



- pict*,- 

- SBODu; 

- opanBlit.epenftefNuiti; 



begin lof DoSaveltem] 

theWlndow ;- FrontWlndow; 

rayUataHandle :- WlndDataH (GetWRefCon (theWindowl > ; 

SFPutFlle (20, 

Z0, 

'Save which picture:', 

myDat aHa n d I e" . Name , 

15, 

myReply) ; 

If myReply.good then begin 
WaltCursor; 

SaveOne (niyDataHandlc".plct) ; 
with myDat aHa rid le A * do begin 

[Change name of correct menu item; \ 
Name S- myReply. filename; 
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Me mist r :- coneat {'-", 

myflepay, filename, 

TntToStrlng [MenuID} , 

for 1 :- FlrstwJnd to LastWlnd do 

if WlDdowLlst (ij - thoWlndow then 
Leave; |Enie loop] 
. r d f SethIte ™ ^^""t^rUftWindlt*. + l>; ( NEW memi name> 

CalcMenusu* (0,0,mndowaMenulD) - 

InitCursor; 
end; 

end; (of DoSaveltemf 

prooedure Paint; 

(This i. , Dafinition PfDMdure USEd to ^ thfl cqntflnts ef a ^^ windo ^ 

var tmpport . GrafPortPtr; 

myOataHandla : WindDataH; 

begin (of Paint J 

tmpFort : - Get Port; 

Paint It ImyDataHandle"* plet) - 
end; f D f Pa i nt | 

procedure Palntlt (pict: Handls); 

procedure tc aotull], draw the picture ln maK)ry to th . wlndotf-| 

var srcLoc : Loelnfc; 
srcRect : Rect; 

begin (of Palntlt I 
HLoe* (pict) ; 



with fircLoc do begin 
portsca 
ptrToPixlmage 
lwldth 



end; 



- 3O08D; 

- pict"; 

-- 160; 

f etR ! C ^ (bounclBRect^ca.fiflO.iOoj; 

BoundaRcct . vl :- 0; ' 



SetHErt [BreSect,0,Q, 640,200) ; 
PProPort (sreloc, 

srcRoct, 
D, 

a, 

STCCapyJ ■ 

HUHLock (piet); 
end; jof Palntlt) 



END. 
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GLOBALS.PAS (global data) 



UNIT Globals; 



l+— 
I 
I 






l-Iodge Podge: An example Apple IIG5 Desktop application 

written by the Apple IIGS Development Team 
Translated La TML Pascal by TML Systems, Inc. 

Copyright (c) 1986-87 by Apple Computer, Inc. 
All Bights ResErvEd 



Pascal UNIT "GLOBALS, PAS" 



Global data structs and inlt routine 



_+} 



INTERFACE 



USES 



HPlntfData, 
HPIntfProc, 
HPIntfPdDaf 



[Hodgepodge Apple I I S3 Toolbox Inter fa eo Units} 



screenMode 
ManX 

M^dScaTi 



$80; (640 mode) 

640; (Max X clamp I should correspond to ScreenJfcde} 

:60f |Max bIee: of scan line! 



AppleManuXD - 300; 

AOoutltesr, - 301; 

E'ileHenuID ~ 400; 

Openltem - 401; 

Closeltem - 255; 

SaveAsltem - 403; 

choosepitejn - 405; 

PageSetltem - 4D6; 

?rlr,tlten - 4 07; 

Quitltem, - 4 09; 

EdltMenuID - 5D0; 

trndoICEin - 25D; 

Cut I tun - 251; 

Copyltem ■ 252; 

PasteltEm - 253; 

claarltem - 254; 

WlndowsHenuID - 6DD; 

NoWindDBlsItEm - SDJj 

FirstMindltem - 2000; 

FontsManuID - 700; 

Font Item - 701; 

Monoltem - 702; 

FirstWind - 0; 

LastWird - 15; 



[For DA's | 



[For DA'fi[ 
[For DA'sJ 
(For DA'M 
[For DA'sJ 
(For DA" at 



(Allocated dynamically starting at 2000} 



(Lower bound of windowltst] 
(Upper bound of WlndowLlsc ] 
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type 



WindDataH 
WLndDataF 
WindDataRee 



"WindDataP; 

^WlndDataRec 
record 

Nans: 
Menu St I 

Flag: 



Strl5S; 
Str255; 

integer; 
integer; 



case integer of 



jRefCon data for our windows) 
(...carried along with kind data) 



Saint, 1 - Font J 



end; 



(thoFnnt: Font IE; 
isMono j boolean) f 
(piet : Handle) ; 



MyHcfiiorylD 
Dona 

ToolsIeroPsge 
Event 

AppleManuStr 

FileMenuStr 

EditManuStr 

WindokJlenuStr 

FontHenustr 

NoKindStr 

HanoSljr ; 

Prostr : 

Lastwindow : 

dummy ; 

OesiredFont : 

laMonoFont : 

myReply . 

PictHndl : 

w-r.dex 
WindowList : 



PlswtTeuip 
Plant Item 

Applelcon 



! Integer; 

: boolean; 

: Handle; 

: WmTaskRec; 

: Str25S; 
: Str255; 

: Strzss,- 
: 5tr255; 

: Str255; 

: String [40]? 
String [40]; 
String [4Dj f 

GrafPcrtPtr; 
integer; 

rant ID ; 

boolean; 

SFRepiyRec; 

Handle; 

Integer; 



(Application ID assigned by HefnQ ^ . 
(True whan quitting) 

I Handle to Zero page memory for Tools I 
I Ml events are returned he, re] 

(For creating menus) 



(Menu Item string for "Bo Hi ndows . . . - ) 



(The front Window last tl« through event 1 
I >!« Possible compiler bug?) 

(Indicates current selected font) 
(Flag indicates if mono spacing selected) 



(Count of number of windows open) 

arrav r f t «h I ° f Up t0 1S °f >en Endows) 

array [JftrstHind. . lastWIndl of GrafPoxtPtr; 

DialogTeraplate; 
ItemTemplate; 



record 

boundsRect 
data 

end; 



Reec; 

array [1..34J of 

Packed array [1..16J of byte; 



procedure InltGiohals* 
PROCEDURE HPStuffKex (thingPtr 



Ptr; s ; 5tr?55); 



(Setup variables) 
(Store he*) 



444 



Appendix G; Hodgepodge Source Code: Pascol 






IMPLEMENTATION 



pRflCEDURE HPStuffHex [thingPtr : Ptr; s : 5tr255]; 

[s!< This routine will be implemented In TKL Pascal VI. 1. For now, 
M define it ouraelvea. SLuiiHex stores bytes (expreased as a string 
of hexadecimal digits] into any data structure, and Is based on the 
StufffteH procedure In Macintosh QuickDraw. The resolution of this 
routine is on byte boundaries.] 

var iterator j integer; 
stringTndex : integer; 

begin to! HPStuffHenl 

for Iterator :- D to Length (s) - 1 do begin 
stringlndes :- (Iterator * 2) + 1; 

thlngptr* :- HeK21nt [StringPtr (longint (Ssl + strlnglndext , 2) ; 
thingPtr :- pointer (longint (thingPtrt + 1! ; 
end; 
end; jof HPStuffHex] 



procedure InitGlobals; 

(Initialize global data variables, Including the FlsHtTemp used by 
ShowPleaseWa It Dialog, the menu strings used by the menu bar setup 
rnutlnas in MENU". PAS, and the Apple icon used by the "about..." 
item dialog routine in DIALOG. PA5| 

begin (of InitGlobals] 

with PlsWtTemp do begin 

SetRect (dtBnundaaect, 120, 3D, 530, 60) ; 

divisible :- true; 

dtHefcon :- o; 

dtltemLlst [0! :- pointer (0); (We will insert ptr to Item here} 

dtttomLlst [1] :- nil; (Null-terminated) 



AppleMenuStr :- concat j 'jsSSNSDaxXO 1 , 

■—About HodgePodgo. ..\K301\0', 

'-— \H30JD\0. ■); 
FlleMenuStf :- concat (■>> File \N40DVO*, 

" —Open . . . \N<01 "0o\D ■ , 

■— Clcse\N255D\0\ 

■--Save A3...\N1D3l>\0 , i 

■ \N40qn\D\ 

1 — Choose Printer... \N4D5\0', 

' --Page Set up . . . \N4 6D\ ■ , 

■--print-. . . \N1Q7-FpD\a 1 , 

•— MHWDVO', 

'-- 0ult\m<J9'Qq\u.'|; 
EditMenuStr J- concat ['» Edit \N5C]uD\u>, 

■--Undt>\N2 5D*Zi\Q\ 

■ ^N5Q1D\U\ 

■ -K:ut\N25i*)(ji\o , 1 

■ -KIopy\N25Z*Ce\0 ■ , 

■ — Paste\N253*W\0 ' , 

'--ClearWSflAO.'l ; 
WindowHenuStr :- concat (■» Window \NfiOC-D\u 1 , 

■— Nd Windows Allacated\N6ulQ\G, '] j 
FontMenuStr :- concat ('» Fonts \H70D\0- , 

'—Display FClnt...^N7ul*Fi■\a , , 

■—Display Font as Hono-spaced\N7DZ*Hm\0 ( '}; 



ListWindow 



nil; 



GLOBALS^PAS (global data) 



twU 



KoWir.dStr 



=No Windows AllooatBd\Mfi01D\D, 



MonoStr :- ■ -Display Font as Mono-spaced"; 

PraStr ;- '-Display Font as Proportional " 

lsMonoFont. : ■* false; 

with DaslredFont do begin 



famN'jm. 

forvtstyXe 

font Size 
end; 

WInd«x :- 0; 

SetRect 

HPStuffHex 
HPStuffHex 
HPStuffHex 
HPStviffHax 
HPStuffHex 
HPStuHHex 
HPStuffHex 
HPStuffHex 
HPStuf tHEii 
flFStuffHex 
HPStuffHex 
HPStuffHex 
HPStuffHex 
HPStuffHex 
HP Stuff Hex 
HPStuffHex 
HPStuffHex 
HPStuffHex 
HP St .j ff Hex 
KPStuf FFSeX 
HPStuffHex 
HPStuffHex 
HPStuffHex 
HPStuf IHek 
HPStuffHex 
HPStuffHen 
HPStuffHEX 
HPStjf t«s.% 
HPStalfffBe* 
HPStuffHex 
HPB tuff Hen 
HP Stuff Hex 
H? Stall EHe* 
HPStufrKex 



- 5FFFE; 

- Of 

- B; 



1 Appl e I con . bounds Beet 
{? Applolcon .data [ 1 ] 
(?AppleIcon.data [ 2 1 
[GApplelcon.data [3] 
( ?AppleIcon.dat a [4] 
(PApploI con. data. [ 5 ] 
(@Appl Eicon, data [ E] 
(SApplelcon. data [ 7 ] 
( SAppl el cor. . da t a [ 8 ] 
(5AppieIcnn.data[ S| 
(SAppieTcon .dataLlO 
(3AppleIcon.dat a [11 
(BApplelter).aata(l2 
{ 5 Applel co n . da t a | 1 3 
(gApplelcOh.data | 14 
(3fl.ppleIcon.dara [ 15 
(BApplelcon. data [16 
{(5 Apple icon, data [17 
(SApplelcon.data [IB 
[SftpplElcon.data [19 
[UApplelcon.data [ID 
[8 Appl el con. data [21 
[?Appleleon.data[22 
(SApplel con. data [23 
[SAjjpleleon.dat a [24 
(SApp'. el con. data [25 
(3 Apple 1 cor. .data [26 
(SApplelcor. .data [27 
(3AppleIcon . data [28 
(3AppleIcofi.data[2 9 
|6Applelcon.dataE30 
(SApp] elcon .dat a [31 
( 6 Applolcon .data (32 
(8Applelcon.data[33 
(BApplelcon .data [34 



[No windows open yet) 
d. 0,64, 34); 

oo o o o oo o oa o o ooo o o oo o oooo o o oq o oa a < 

0FFF FFFFFFFFF FFFF FFFFFFFF FFFFFFO ' 
■OF0000000OO000D000O000D00ODOOOFC 1 
'OFOFFFFFFFFFFFFFFFFFFFFFFFFFFOFC 
'OFOFFFFFFFFFFFFFFFFFFeSFFFFFFOFO' 
'DFDFFFFFFFFFFFFFFFFBBBBFFFFFFOFD' 
'DFDFFFFFFFFFFFFFFrBBBBBFFFFFFOFD' 
'OFOFFFFFFFFFFFFFFSBBBaFFFFFFFOFD' 
, OFDFFFFFFFFFFFFFa8BBBaFFFFFFFvF0■ 
'OFOFFFFFFFFFFFFFBflBBBFFFFFFFFaFO 1 
'QTQFFFFFFFFFFFFFBBBBFFFFFFFFFOFO' 
'OFOFFFFFFeBBBFFFSBFFBSaaf'FFFFOFO 1 
l 0F0FFFFBB8S8BflBFFFB8Ba8BBBF^F0F0■ 

'OFOFFFBBBeseeaasBeeeeaeSBBBFFOFO 1 

1 F0 F Fee eeee eeeeeeeee eeeee F FFF 0F0 ' 
'OFOFFeeeeeeeeeeeaeeeeeeeFFFFFOFO' 
' OFOf Fee o aeeeeeeo e aceoeeFFF FFF0F0 ' 
l OFaFF66fi6666666666S6666FFFFFF0FO , 
•OFOFF666e6S£66S46«66S66FFFFFF0FO < 
'OFOFF66666660666666666SFFFFFF0FO* 
■OFOFF44444 4 444 44444 4 444 4FFFFF0FO ' 
■DFCFF44444 4 44444444 4 444 44FFFF0FD' 
■DF0FFF4444 4 44444444 4 444 4444FF0FD' 
■ 0FOFFF5555555555 5 55555555 55FFOFD ■ 
'0F0FFF5555555S555 55555555 5 5FFOF0 1 
■ 0FDFFFF55S5555S555S555555:SFFFOFu ■ 
■OFDFFFFlllllllll 1111 11111 1FFFOF0 1 
■ 0F0FFFFF11111111 1111 lllllFFFf DFO ' 
■0F0FFFFFF111111FFF111111FFFFFDFD' 
■OFOFFFFFFFllUFFFFFllllFFFFFFOFO 1 
■ OFOFFFFFFFFFFFFFFFFFFFFFFFFFFDFU ' 

■ OFOoaaDDDooooooDooooooaoooooooFO ■ 

■ QFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFO ■ 
' 00000000000000000000000000000000 ' 



end; 



(of InltGlobalB[ 
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Glossary 



absolute: Characteristic of a load segment or 
other program code that must be loaded at a 
specific address in memory and never moved. 
Compare relocatable, position-Independent. 

absolute addressing: an addressing mode in 
which instruction operands are interpreted as 
literal addresses. 

access (or access byte): An attribute of a ProDOS 
file that controls whether the file may be read 
from, written to, renamed, or backed up. 

accumulator: The register in a computers central 
processor or microprocessor where most 
computations arc performed, 

activate: To make active. A control or window 
may be activated. Compare enable, 

activate event: a window event that occurs when a 
window is made either active or inactive. 

active: Able to respond to the user's mouse or 
keyboard actions. Controls and windows that are 
active are displayed differendy from inactive 
items. 

ADB: See Apple Desktop Bus. 

address bus: The bus that carries addresses from 
the CPU to components under its control. 



advanced linker (AFW): One aspect or the linker 
supplied with APW. The operation of the 
advanced linker is programmable. Compare 
standard I inker. 

alert: A warning or report of an error in the form 
of an alert box, a sound from the computer's 
speaker, or both. 

alert box: A special type of dialog box that 
appears on the screen to give a warning or to 
report an error message during use of an 
application. 

alert window: 'Hie window in which an alert box 
appears. One of the two predefined window 
formats. Compare document window. 

analog RGB: A type of color video consisting of 
separate analog signals from die red, green, and 
blue color primaries. The intensity of each 
primary can vary continuously, making possible 
many shades and Lints of colors. Compare TTL 
RGB. 

Apple Desktop Bus (ADB): An input bus, with its 
own protocol and electrical characteristics, that 
provides a method of connecting input devices 
such as keyboards and mouse devices to personal 
computers. 

Apple Desktop Bus Tool Set: The Apple 1IGS tool 
set that facilitates an application's interaction 
with devices connected to the Apple Desktop 
Bus. 
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Apple key: A modifier key on the Apple 11GS 
keyboard, marked with both an Apple icon and a 
spinner, the icon used on the equivalent key on 
some Macintosh keyboards. It performs the same 
functions as the Open Apple key on standard 
Apple II machines. 

Apple Talk network: A local area network 
developed by Apple Computer, Inc. 

Apple II: A family of computers, including the 
original Apple II, the Apple II Plus, the Apple He, 
the Apple He, and the Apple 1IGS. Compare 
standard Apple II. 

Apple nc A transportable personal computer in 
the Apple II family, with a disk drive, serial ports, 
and 80-column display capability built in, 

Apple lie: A personal computer in the Apple II 
family with seven expansion slots and an 
auxiliary memory slot that allow the user to 
enhance the computer's capabilities with 
peripheral memory and video enhancement 
cards, 

Apple IIGS; The most advanced computer in the 
Apple II family. It features expanded memory, 
advanced sound and graphics, and the Apple 
IIGS Toolbox of programming routines. 

Apple IIGS Debugger: A 65&16 machine language 
code debugger for the Apple IIGS computer. 

Apple IIGS Programmers Workshop fAFW); A 

multi language development environment for 
writing Apple IIGS desktop applications. 

Apple IIGS Toolbox; An extensive set of routines 
that facilitate writing desktop applications and 
provide easy program access to many Apple HG5 
hardware and firmware features. 

Apple H Plus: A personal computer in the Apple 
II family with expansion slots that allow the user 
to enhance the computer's capabilities with 
peripheral cards. 






application; A stand-alone program that 
performs a specific function, such as word- 
processing, drawing, or telecommunications. 
Compare, for example, desk accessory or device 
driver. 



application -de fined event: Any of four types of 
events available for applications to define and 
respond to as desired. 

application prefix: The ProDOS 16 prefix number 
1 / , It specifies the directory of the currently 
running application. 

application window; A window in which an 
application's document appears. 

APW: Sec Apple IIGS Programmer's Workshop. 

APW Assembler: The 65816 assembly-language 
assembler provided with the Apple IIGS 
Programmer's Workshop. 

APW C Compiler: The C- language compiler 
provided with the Apple HGS Programmer's 
Workshop, 

APW Editor; The program within the Apple IIGS 
Programmer's Workshop that allows you to enter, 
modify, and save source files for all APW 
languages. 

APW Linker: The linker supplied with the 
Apple IIGS Programmer's Workshop. 

APW Shell: The programming environment of 

the Apple IIGS Programmer's Workshop — it 
provides facilities for file manipulation and 
program execution, and supports shell 
applications, 

APW utility program: Any of various Shell 
applications supplied with the Apple IIGS 
Programmer's Workshop that function as APW 
Shell commands. 

arc: A portion of an oval; one of the fundamental 
shapes drawn by QuickDraw II. 

A register: See accumulator. 
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ascent: In a font, the distance between the base 
line and the ascent tine. 

ascent line: A horizontal line that coincides with 
the tops of the tallest characters in a font. See 
also base line, descent line. 

ASCII; Acronym for American Standard Code for 
Information Interchange, pronounced "ASK-ee." 
A code in which the numbers from to 127 stand 
for text characters. ASCII code is used to 
represent text inside a computer and to transmit 
text between computers or between a computer 
and a peripheral device. 

assembler: A language translator that converts a 
program written in assembly language into an 
equivalent program in machine language. The 
opposite of a disassembler. 

attributes wor<L Determines how memory blocks 
are allocated and maintained. Most of the 
attributes are defined at allocation time and can't 
be changed after that; other attributes can be 
modified after allocation. 

auto-keys A keyboard feature and an event type, in 
which a key being held down continuously is 
interpreted as a rapid series of identical 
keystrokes, 

auxID: A subfield of the User ID, An application 
may place any value it wishes into the auxID 
field. 

auxiliary type: A secondary classification of 
ProDOS files. A file's auxiliary lype field may 
contain information of use to the applications 
that read it. Compare file type. 

background: The pixels within a character or 
other screen object that are not part of the 
object itself. 

background color. The color of background 
pixels in text, by default it is black. 

background pattern; The pattern QuickDraw It 
uses to erase objects on the screen. 



background pixels: In a character image, the 
pixels that are not part of the character itself. 

background procedure: A procedure run by the 
Print Manager whenever the Prim Manager has 
directed output to the printer and is waiting for 
the printer to finish. 

backup bit: A bit in a file's access byte that tells 
backup programs whether the file has been 
altered since the last lime h was backed up. 

bank: A 64K (65,536-byte) portion of the Apple 
IIGS internal memory. An individual bank is 
specified by the value of the 65816 
microprocessor's bank register. 

bank- switched memory: On Apple II computers, 
the part of language card memory in which two 
4K portions of memory share the same address 
range (SD00O to SDFFF). 

bank $00: The first bank of memory in the Apple 
IIGS. In emulation mode, it is equivalent to main 
memory in an Apple He or Apple lie computer. 

base line: A horizontal line that coincides with 
the bottom of the main body of each character 
in a font. Character descenders extend below the 
base line. 

BASIC: Acronym for Beginners Alt-purpose 
Symbolic Instruction Cods. BASIC is a high-level 
programming language designed to be easy to 
learn. Applesoft BASIC is built into the Apple 
IIGS firmware. 

batch: A mode of executing a computer program 
in which all code and data required by the 
program are loaded into the computer at the 
beginning, the program is run, and all results are 
output at the end. Batch mode is non-interactive. 

binary file; 0) A file whose data is to be 
interpreted in binary form. Machine-language 
programs and pictures are stored in binary files. 
Compare text file. (2) A file in binary file format. 
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binary file format The ProDOS 8 loadable file 
format, consisting of one absolute memory 
image along with its destination address. A file in 
binary file format has ProDOS file type $06 and 
is referred to as a BIN file. The System Loader 
cannot load BIN files. 

bit: A contraction of binary digit, the smallest 
representation of data in a digital computer. 

bit plane: A method of representing images in 
computer memory. In a bit plane, consecutive 
bits in memory specify adjacent pixels in the 
image; if more than one bit is required to 
completely specify the state of a pixel, more than 
one bit plane is used for the Image. Compare 
chunky pixels. 

block; (1) A unit of data storage or transfer, 
typically 512 bytes. (2) A contiguous region of 
computer memory of arbitrary size, allocated by 
the Memory Manager. Also called a memory 
block. 

block device: A device that transfers data to or 
from a computer in multiples of one block (512 
bytes) of characters at a time. Disk drives are 
block devices. Also called block I/O device. 

Boolean logic: A mathematical system in which 
every expression evaluates to one of two values, 
usually referred to as TRUE or FALSE. 

Boolean variable: A variable that can have one 
of two values, usually referred to as TRUE or 
FALSE. 

boot prefix: The ProDOS 16 prefix number */. It 
specifies the name of the volume from which the 
currently running version of ProDOS 16 was 
started up. 

boundary rectangle: A rectangle, defined as part 
of a QuickDraw II Loclnfo record, that encloses 
the active area of the pixel image and imposes a 
coordinate system on it. Its upper-left corner is 
always aligned on the first pixel in the pixel map. 

bounds Rect; The GrafPort field that defines the 
port's boundary rectangle. 



breakpoint; A machine-language instruction in a 
program that causes execution to halt. 

buffer: A holding area of the computer's memory 
where information can be stored by one 
program or device and then read, perhaps at a 
different rate, by another; for example, a print 
buffer. 

Busy flag: A feature that informs the Scheduler 
whether a currently needed resource is busy or 
available. 

burton: (1) A pushbutton-like image in a dialog 
box where the user clicks to designate, confirm, 
or cancel an action. Compare radio button, 
check box. (2) A button on a mouse or other 
pointing device. 

byte: A unit of information consisting of eight 
bits. A byte can have any value between and 
255, which may represent an instruction, letter, 
number, punctuation mark, or other character. 
See also bit, kilobyte, megabyte. 

C: A high-level programming language. One of 
the languages available for the Apple IIGS 
Programmer's Workshop. 

cancel: To stop an operation, such as the setting 
of page-setup values in a dialog box, without 
saving any results produced up to that point. 

Cancel; One of two predefined item ID numbers 
for dialog box buttons (Cancel = 2). Compare 
OK. 



card: See peripheral card. 






caret: A symbol that indicates where something 
should or will be inserted in text. On the screen it 
designates the insertion point, and is usually a 
vertical bar ( I ), 

carry flag: A status bit in the microprocessor 
indicating whether an accumulator calculation 
has resulted in a carry out of the register. 

CDA: See classic desk accessory. 

c flag: See carry Hag. 
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character: Any symbol that has a widely 
understood meaning and thus can convey 
information. Some characters — such as letters, 
numbers, and punctuation — can be displayed on 
the monitor screen and printed on a printer. 
Most characters are represented in the computer 
as one -byte values. 

character device: A device that transfers data to 
or from a computer as a stream of individual 
characters. Keyboards and printers are character 
devices. 

character image: An arrangement of bits that 
defines a character in a font. 

character origin: The point on the base line used 
as a reference location for drawing a character. 

character width,- The number of pixels the pen 
position is to be advanced after the character is 
drawn. 

check box: A small box associated with an option 
in a dialog box. When the user clicks the check 
box, that may change the option or affect related 
options. 

Choose Printer: A part of the Print Manager that 
lets the user select a printer or port for printing. 

chunklness: The number of bits required to 
describe the state of a pixel in a pixel image. 

chunky pixels: A method of representing images 
in computer memory. In chunky pixel 
organization, a number of consecutive bits in 
memory combine to specify the state of a single 
pixel in the image. Consecutive groups of bits 
(the size of the group is equal to the image's 
chunklness) define adjacent pixels in the image. 
Compare bit plane. 

clamp values: The x- and y-limits, in terms of 
pixels, on cursor position controlled by mouse 
movement, 



classic desk accessory (CDA): Desk accessories 
designed to execute in a non-desktop, non-event- 
based environment. Compare new desk 
accessory, 

click: To position the pointer on something, and 
then to press and quickly release the button on 
the mouse or other pointing device. 

clip: To restrict drawing to within a particular 
boundary; any drawing attempted outside that 
boundary does not occur. 

Clipboard: 'Ine holding place for what the user 
last cut or copied; a buffer area in memory, 
information on the Clipboard can be inserted 
(pasted) into documents. In memory, the 
contents of the Clipboard are called the desk 
scrap. 

clipping region: The region to which an 
application limits drawing in a GrafPort. 

clock: (1) The timing circuit that controls 
execution of a microprocessor. Also called the 
system clock. (2) An integrated circuit, often with 
battery-backup memory, that gives the current 
date and time. Also called the clock-calendar, 

dock speeds The frequency of the system clock 
signal in megaherte, 

close box; The small white box on the left side of 
die tide bar of an active window. Clicking it 
closes the window, 

CMOS: Abbreviation for complementary meial- 
oxide semiconductor, one of several methods of 
making integrated circuits out of silicon. CMOS 
devices are characterized by their low power 
consumption, CMOS techniques are derived 
from MOS techniques. 

color table: One of 16 possible lookup tables in 
Apple JIGS memory, that lists the available color 
values for a scan line. 
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command line: CI) In APW, the line of text with 
which the user invokes a procedure or function 
or executes a program. The command line often 
includes both the name of the function to 
execute and a list of parameters to be passed to 
the function. (2) The line on the screen on which 
a command is entered. 

command-line interface; The type of interface 
between user and program in which information 
is passed in a command line. 

compaction: The rearrangement of allocated 
blocks in memory to open up larger contiguous 

areas of free space. 

compiler; A program that produces object files 
(containing machine-language code) from source 
files written in a high-level language such as C. 
Compare assembler. 

content region: The area in a window in which an 
application presents information to the user. 

control: An object in a window with which the 
user, using the mouse, can cause instant action 
with visible results or change settings to modify a 
future action. 

controlling program: A program that loads and 
runs other programs, without itself leaving 
memory. A controlling program is responsible 
for shutting down its subprograms and freeing 
their memory space when they are finished. A 
shell, for example, is a controlling program. 

Control Manager: The Apple IIGS tool set that 
manages controls. 

Control Panel: A desk accessory that lets the user 
change certain system parameters, such as 
speaker volume, display colors, and configuration 
of slots and ports 

coordinate plane: A two-dimensional grid 
defined by QuickDraw II. All drawing commands 
are located in terms of coordinates on the grid. 



coordinates: 3C-Y locations on the QuickDraw I] 
coordinate plane. Most QuickDraw routines 
accept and return coordinates in the order CY,K). 

copy: To duplicate something by selecting it and 
choosing Copy from the Edit menu. A copy of 
the selected porEion is placed on the Clipboard, 
without affecting the original selection. 

creation date: An attribute of a ProDOS file; it 
specifies the date on which the file was first 
created. 

creation time: An attribute of a ProDOS file; it 
specifies the lime at which the file was first 
created. 

C string: An ASCII character string terminated by 
a null character (ASCII value = 0). 

cursor: A symbol displayed on the screen 
marking where the user's next action will take 
effect or where the next character typed from the 
keyboard will appear. 

cut: To remove something by selecting it and 
choosing Cut from the Edit menu. The cut 
portion is placed on the Clipboard. 

data area; A document as viewed in a window. 
The data area is the entire document, only a 
ponion of which (the visible region) may be 
seen in the window at any one time. 

data bank register: A register in the 65816 
processor that contains the high-order byte of 
the 24-bit address that references data in 
memory. 

data bus: A set of the electrical conductors that 
carry data from one internal part of the 
computer to another. 

data structure: A specifically formatted item of 
data or a form into which data may be placed, 

DB register: See data bank register. 
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debugger: A utility used for software development 
that allows you to analyze a program for errors 
that cause it to malfunction. For example, it may 
allow you to step through execution of the 
program one instruction at a time, 

default prefix: The pathname prefix attached by 
ProDOS 16 to a partial pathname when no prefix 
number is supplied by the application. The 
default prefix is equivalent to prefix number 0/, 

definition procedure: A routine that defines the 
characteristics of some desktop feature such as a 
window or control. For example, TaskMaster 
needs a pointer to a window-content dejlntton 
procedure (wContDefP roc) In order to draw the 
contents of windows that it manipulates. 

DefProc See definition procedure. 

dereference: To substitute a pointer for a 
memory handle, or a value for a pointer. When 
you dereference a memory block's handle, you 
access the block directly (through its master 
pointer) rather than indirectly (through its 
handle). 

descender: Any part of a character that lies 
below the base line (such as the tail on a lower- 
case "p") . 

descent: In a font, the distance between the base 
line and the descent line. 

descent line: A horizontal line that coincides with 
the bottom of the character descender that 
extends farthest below the base line. See also 
ascent line, font height 

desk accessory: A "mini-application" that is 
available to the user regardless of whether 
another application is running. The Apple IIGS 
supports two types of desk accessories: classic 
desk accessories and new desk accessories, 

desk accessory event: An event that occurs when 
the user enters the special keystroke 
(Control-Apple-Escape) to invoke a classic desk 
accessory. 



Desk Manager: The Apple IIGS tool set that 
executes desk accessories and enables 
applications to support them. 

desk scrap: A piece of data, maintained by the 
Scrap Manager, taken from one application and 
available for insertion into another. 

desktop: The visual interface between the 
computer and the user— the menu bar and the 
gray (or solid-colored) area on the screen. In 
many applications the user can have a number of 
documents on the desktop at the same time. 

desktop Interface: See desktop. 

destination: Sec destination location. 

destination location: The location (memory 
buffer or portion of the QuickDraw II coordinate 
plane) to which data such as text or graphics is 
copied. Compare source location. See also 
destination rectangle. 

destination rectangle; The rectangle (on the 
QuickDraw II coordinate plane) in which text or 
graphics are drawn when transferred from 
somewhere else. Compare source rectangle. 

development environment; A program or set of 
programs that allows you to write applications. It 
typically consists of a text editor, an assembler or 
compiler, a linker, and support programs such as 
a debugger. 

device: A piece of hardware used in conjunction 
with a computer and under the computer's 
control. Also called a peripheral device because 
such equipment is often physically separate from, 
but attached to, the computer. 

device driver: A program that handles the 
transfer of data to and from a peripheral device, 
such as a printer or disk drive, 

device-driver event: An event generated by a 
device driver. 
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dial; An indicator on Lhc screen lhat displays a 
quanlativc setting or value. Usually found in 
analog form, such as a fuel gauge or 
thermometer. A scroll bar is a standard type of 
dial. 

dialog; See dialog box, 

dialog box: A box on the screen that contains a 
message requesting more information from the 
user. See also alert. 

Dialog Manager: The Apple II GS tool set lhat 
manipulates dialog boxes and alerts, which 
appear on the screen when an application needs 
more information to carry out a command or 
when the user needs to be notified of an 
important situation. 

dialog record: information describing a dialog 
window that is maintained by the Dialog 
Manager. 

dialog window: The window in which a dialog box 
appears. 

digital oscillator chip (DOC): An integrated 
circuit in the Apple IIGS lhat contains 32 digital 
oscillators, each of which can generate a sound 
from stored digital waveform data. 

digital RGB video monitor: A type of RGB video 
display in which the intensities of the red, green, 

and blue signals are fixed at discrete values, 

dim: On the Apple IIGS desktop, to display a 
control or menu item in gray rather than black, 
to notify the user lhat the item is inactive. 

direct pages A page (256 bytes) of bank $00 of 
Apple IIGS memory, any part of which can be 
addressed with a short (one-byte) address 
because its high-order address byte is always $00 
and its middle address byte is ihe value of the 
65816 direct register. Co-resident programs or 
routines can have their own direct pages at 
different locations. The direct page corresponds 
to the 6502 processor's zero page. The term 
direct page is often used informally to refer to 
any part of the direct-page/stack space. 



direct- page/stack segment A program segment 
that is used to initialize the size and contents of 
an application's stack and direct page. 

direct- page/stack space: A single block of 
memory lhat contains an application's stack and 
direct page. 

direct register: A hardware register in the 65816 
processor that specifies the start of the direct 
page. 

disable: To make unresponsive to user actions. A 
dialog box control that is disabled does nothing 
when selected or manipulated by the user. In 
appearance, however, it is identical to an enabled 
control. Compare inactive. 

disabled menu: A menu that can be pulled down, 
but whose items are dimmed and not selectable. 

disassembler: A program thai converts machine- 
language code in memory into assembly- 
language instructions. Opposite of assembler. 

disk operating system: An operating system 
whose principle function is to manage disk-based 
file access. 

disk port: The connector on the rear panel of the 
Apple IIGS for attaching disk drives. 

Disk II: A type of disk drive made and sold by 
Apple Computer, Inc., for use with the Apple II, H 
Plus, and lie computers. It uses 5. 25-inch disks. 

display mode: A specification for the way In 

which a video display functions, including such 
parameters as whether displaying text or 
graphics, available colors, and number of pixels. 
The Apple 11 GS has two text display modes (40 
column and 80 column), two standard Apple II 
graphics display modes (Hi-Jtes and Double 
Hi-Res), and two new Super Hi-Res graphics 
display modes (320 mode and 640 mode). 

display rectangle: A rectangle that determines 
where an item is displayed within a dialog box. 
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dispose: To permanently deallocate (a memory 
block). The Memory Manager disposes of a 
memory block by removing its master pointer. 
Any handle to that pointer will then be invalid. 
Compare purge. 

dithering: A technique for alternating the values 
of adjacent pixels to create the optical effect of 
intermediate values. Dithering can give the effect 
of shades of gray on a black-and-white display, or 
more colors on a color display. 

DOC: See digital oscillator chip. 

document: A file created by an application. 

document windows A window that displays a 
document. One of the two predefined window 
formats. Compare alert window, 

dormant; Said of a program that is not being 
executed, but whose essential parts are all in the 
computer's memory. A dormant program may 
be quickly restarted because it need not be 
reloaded from disk. 

double-click: To position the pointer where you 
want an action to take place, and then press and 
release the mouse button twice in quick 
succession without moving the mouse. 

draft printing; The print method III at the 
LaserWriter uses. QuickDraw II calls are convened 
directly into command codes the printer 
understands, which are then immediately used to 
drive the printer, Compare spool printing, 

drag; To position the pointer on something, 
press and hold the mouse button, move the 
mouse, and release the mouse button. When you 
release the mouse button, you either confirm a 
menu selection or move an object to a new 
location. 

drag area; A subregion in a window (usually the 
title bar) in which the mouse pointer must be 
placed before the user can drag the window, 

draw: In QuickDraw II, to color pixels in a pixel 
image. 



drawing environment; The complete description 
of how and where drawing may take place. Every 
open window on the Apple IIGS screen is 
associated with a GrafPort record, which specifies 
the window's drawing environment. Same as port, 
graphic port. 

drawing mask: An 8-bit by B-bil pattern that 
controls which pixels in the QuickDraw pen will 
be modified when the pen draws. 

drawing mode: One of eight possible interactions 
between pixels in QuickDraw IPs pen pattern and 
pixels already on the screen that fall under the 
pen's path. In COPY mode, for example, pixels 
already on the screen are ignored. In XOR mode, 
on the other hand, bits in pixels on the screen 
are XOR'd with bits in pixels in the pen; the 
resulting pixels are drawn on the screen. 

drawing pert See pen. 

D register; See direct register. 

driver; See device driver. 

dynamic segment; A load segment capable of 
being loaded during program execution. 
Compare static segment 

edit record: A complete text editing environment 
in the Line Edit Tool Set, which includes the text 
to be edited, the GrafPort and rectangle in which 
to display the text, the arrangement of the text 
within the rectangle, and other editing and 
display information. 

e flag: One of three flag bits in the 65816 
processor that programs use to control the 
processor's operating modes. The setting of the e 
flag determines whether the processor is in 
native mode (6502), or emulation mode (65816). 
See also m flag and x flag. 

emulate; To operate in a way identical to a 
different system, For example, the 65816 
microprocessor in the Apple IIGS can carry out 
all the instructions in a program originally 
written for an Apple II that uses a 6502 
microprocessor, thus emulating the 6502. 
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emulation mode: The 8-bit configuration of the 
65816 processor in which it functions like a 6502 
processor in all respects except clock speed, 

enable: To make responsive to user manipulation. 
A dialog or menu that is enabled can be selected 
by the user, Enabling does not affect how an item 
is displayed. Compare activate. 

end-of-fllfe See EOF, 

EOF: The logical size of a ProDOS 16 file; it is the 
number of bytes that may be read from or 
written Lo the file. 

erase: In QuickDraw II, to color an area with the 
background pattern. 

error: The state of a computer after it has 
detected a fault in one or more commands sent 
to it. Also called error condition. 

error message: A message issued by the system or 
application program when it has encountered an 
abnormal situation or an error in data. 

event: A notification to an application of some 
occurrence (such as an interrupt generated by a 
keypress) to which the application may want to 
respond. 

event code: A numeric value assigned to each 
event by the Event Manager. Compare task code. 

event-driven : A kind of program that responds to 
user inputs in real time by repeatedly testing for 
events. An event-driven program does nothing 
until it detects an event such as a click of the 
mouse button. 

Event Manager: An Apple 1IGS tool set that 
detects events as they happen, and passes the 
events on to the application or to the 
appropriate event handler, such as TaskAt aster. 

event mask: A parameter passed to an Event 
Manager routine to specify which types of events 
the routine should apply to. 

event queue: A list of pending events maintained 
by the Event Manager. 



event record: The internal representation of an 
event, through which your program learns all 
pertinent information about that event. 

execution mode: One of two general states of 
execution of the 65816 processor — native mode 
and 6502 emulation mode, 

extended task event record- A data structure 
based on the event record that contains 
information used and returned by TaskMaster. 

FALSE: Zero. The result of a Boolean operation 
Opposite of TRUE, 

file: Any named, ordered collection of 
information stored on a disk. Application 
programs and operating systems on disks are 
examples of files; so also arc text or graphics 
created by applications and saved on disks. Text 
and graphics files are also called documents 

file level: See system file leveL 

file mark: See Mark, 

filename: The string of characters that identifies a 
particular file within its directory. ProDOS 
filenames may be up to 15 characters long, 
Compare pathname. 

file type: An attribute of a ProDOS file that 
characterizes its contents and indicates how the 
file may be used, On disk, file types are stored as 
numbers; in a directory listing, they are often 
displayed as three-character or single- word 
mnemonic codes. 






fill mode: A display option in Super Hi-Res 320 
mode. In fill mode, pixels in memory with the 
value are automatically assigned the color of 
the previous nonzero pixel on the scan line; the 
program thus need assign explicit pixel values 
only to change pixel colors. 
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firmware: Programs stored permanently in ROM; 
most provide an interface to system hardware. 
Such programs (for example, the Monitor 
program) are built into the computer at the 
factory. They can be executed at any time but 
cannot be modified or erased. Compare 
hardware and software. 

fixed: Not movable in memory once allocated. 
Also called immovable. Program segments that 
must not be moved are placed in fixed memory 
blocks. Opposite of movable. 

fixed-address: A memory block that must be at a 
specified address when allocated. 

fixed-bank: A block of memory that must start in 
a specified bank. 

flag: A variable whose value (usually 1 or 0, 
standing for true or false) indicates whether some 
condition holds or whether some event has 
occurred. A flag is used to control the program's 
actions at some later time, 

folder: See subdirectory. 

font; In typography, a complete set of type in one 
size and style of character, In computer usage, a 
collection of letters, numbers, punctuation marks, 
and other typographical symbols with a 
consistent appearance; the size and style can be 
changed readily. See also font scaling. 

font family: All fonts that share the same name 
but may vary in size or style. For example, all 
fonts named Helvetica are in the same family, 
even though that family contains Helvetica, 
Helvetica Narrow and Helvetica Bold. 

font height: The vertical distance from a font's 
ascent line to its descent line. 

font ID: A number that specifies a font by family, 
style, and size. 

font scaling: A process by which the Font 
Manager creates a font at one size by enlarging 
or reducing characters in an existing font of 
another size. 



font strike: A 1 bit/pixel pixelmap consisting of 
the character images of every defined character 
in the font, placed sequentially in order of 
increasing ASCII code. 

foreground color: The color of the foreground 
pixels in text; by default it is white. 

foreground pixels: In a character image, the 
pixels corresponding to the character itself. 

frame region: The part of a window ihat 
surrounds the window's content region and 
contains standard window controls, 

full pathname: The complete name by which a 
file is specified, starting with the volume 
directory name. A full pathname always begins 
with a slash (/), because a volume directory 
name always begins with a slash. See also 
pathname. 

Function Pointer Table (FFT): A table, 
maintained by the Tool Locator, that points to all 
routines in a given tool set. 

general logic unit See GLU. 

GetNextEvenfc The Event Manager call lhat an 
application can make on each cycle through its 
main event loop. Compare TaskMaster. 

global coordinates: The coordinate system 
assigned to a pixel image (such as screen 
memory) to which QuickDraw II draws. In global 
coordinates, the origin (upper-left corner) of the 
pixel image's boundary rectangle has the value 
(0,0). Compare local coordinates. 

global symbol; A label in a segment that may be 
referenced by other segments. Compare with 
local symbol, private symboL 

GLU; Abbreviation of general logic unit, a class of 
custom integrated circuits used as interfaces 
between different parts of the computer. 

go-away area: A subregion in a window frame, 
corresponding to the close box. Clicking inside 
this region of the active window makes the 
window close or disappear. 
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GrafPort: A data structure (record) that specifies 
a complete drawing environment, including such 
elements as a pixel image, boundaries within 
which to draw, a character font, patterns for 
drawing and erasing, and other pen 
characteristics. 

graphic interface: An interface between computer 
and user in which all screen drawing or other 
output, including text, is done by graphic 
routines. Desktop programs use a graphic 
interface. Compare text-based Interface. 

graphic port; A specification for how and where 
QuickDraw II draws. A graphic port is defined by 
its GrafPort record; an application may have 
more that one graphic port open at one time, 
each defined by its own GrafPort, Same as 
drawing environment 

grow area: A window-frame subregion in which 
dragging changes the size of the window, 

handle: See memory handle, 

hardware: In computer terminology, the 
machinery that makes up a computer system. 
Compare firmware, software. 

Heartbeat Interrupt Task queue: A list of tasks, 
such as cursor-movement updating or checking 
stack size, to be performed during vertical 
blanking. Heartbeat tasks are manipulated by the 
Miscellaneous Tool Set. 

Heartbeat routines! Routines that execute at some 
multiple of the heartbeat interrupt signal, which 
occurs during the vertical blanking interval 
(every '/«o of a second). 

hex: See hexadecimal. 

hexadecimal: The representation of numbers in 
the base-16 system, using the ten digits through 
9 and the six letters A through F, Each 
hexadecimal digit corresponds to a sequence of 
four binary digits (bits). Hexadecimal numbers 
are usually preceded by a dollar sign ($). 



hide: To make invisible (but not necessarily to 
discard) an object on the screen such as a 
window. 

highlight: To make something visually distinct. 
For example, when a button on a dialog box is 
selected, it appears as light letters on a dark 

background, rather than dark-on-light. An active 
window or control is highlighted differently than 
an inactive one. 

HodgePodge: A sample Apple IIGS desktop 
application; the program described in this book. 

horizontal blanking: The interval between the 
drawing of each scan line on a video display. 

Human Interface Guidelines: Apple Computer's 
set of conventions and suggestions for writing 
desktop programs. Programs that follow the 
Human Interface Guidelines present a consistent 
and friendly interface to users. 

IC: See integrated circuit 

icon: An image that graphically represents an 
object, a concept, or a message. 

I flag: A bit in the 65816 microprocessor's 
Processor Status register that, if set to 1, disables 
interrupts. 

I mage i A representation of the contents of 
memory, A code image consists of machine- 
language instructions or data thai may be loaded 
unchanged into memory. See also pixel image. 

inactive: Controls that have no meaning or effect 
in the current context, such as an Open button 
when no document has been selected to be 
opened. These inactive controls are not affected 
by the user's mouse actions and are dimmed on 
the screen. Compare disable. 

Index register: A register in a computer processor 
that holds an index for use in indexed 
addressing. The 6502 and 65816 microprocessors 
used in the Apple II family of computers have 
two index registers, called the X register and the 
Y register. 
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information bar; An optional component of a 
window. If present, the information bar appears 
just below the title bar. It may contain any 
information the application that created the 
window wishes. 

initialization file; A program (in the 
SYSTEM, SETUP subdirectory of the boot disk) 
that is loaded and executed at system startup, 
independently of any application. 

initialization segment A segment in an initial 
load file that is loaded and executed 
independently of the rest of the program. It is 
commonly executed first, to perform any 
initialization that the program may require. 

inputfoutput: See I/O. 

insertion point: The place in a document where 
something will be added; it is selected by clicking 
and is normally represented by a blinking 
vertical bar. 

Instrument: A data structure, used by the Note 
Sequencer and Synthesizer, that specifies such 
parameters as the amplitude envelope, pitchbend 
and vibrato characteristics, and the specific 
waveforms that characterize the sound to be 
played. 

integer: A whole number in fixed-point form. 

Integer Math Tool Set: The Apple IIGS tool set 
that performs simple mathematical functions on 
integers and other fixed-point numbers and 
converts numbers to their ASCII string 
equivalents. 

integrated circuit An electronic 
circuit — including components and 
interconnections — entirely contained in a single 
piece of semiconducting material, usually silicon. 
Often referred to as a chip- 
interface: (1> The general form of interaction 
between a user and a computer. (2) In 
programming, the compilc-time and runtime 
linkage between your program and toolbox 
routines. 



Interface library: A set ot vanaoie aennmuiis *uu 
data -structure definitions thai link a program 
(such as a C application) with software written in 
another language (such as the Apple IIGS 
Toolbox). 

interrupt: A temporary suspension in the 
execution of a main program that allows the 
computer to perform some other task, typically 
in response to a signal from a peripheral device 
or other source external to the computer. 

interrupt environment: The machine state, 
including register length and contents, within 
which the interrupt handler executes. 

invert: To highlight by changing white pixels to 
black and vice versa. 

I/O: Inpul/Output. A general term that 
encompasses input/output activity, the devices 
that accomplish it, and the data involved. 

I/O space: The portion of the memory map in a 
standard Apple II (and in banks $00, $01, $E0, 
and SE1 of an Apple IIGS) with addresses 
between SCO00 and SCFFF. Programs perform 
I/O by writing to or reading from locations in 
this I/O space. 

item: A component of a dialog box, such as a 
button, text field, or icon, 

item ID: A unique number that defines an item in 
a dialog box and allows further reference to it. 

item line: The line of text that defines a menu 
item's name and appearance. 

item list: A list of information about all the items 
in a dialog or alert box. 

item type: Identifies the type of dialog item, 
usually represented by a predefined constant 
(such as editions) or a series of constants 
(such as editLine+iteniDisable). 

Job dialog box; A dialog box presented when the 
user selects Print from the File menu. 
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joystick; A peripheral device with a lever, 
typically used to move creatures and objects in 
game programs; a joystick can also be used in 
applications such as computer-aided design and 
graphics programs. 

JSL: Jump to Subroutine (Long), a 65816 assembly- 
language instruction that requires a long O-byle) 
address. JSL can be used to transfer execution to 
code in another memory bank, 

JSR: Jump to Subroutine, a 6502 and 65816 
assembly- language instruction that requires a 2- 
byte address. 

Jump Table: A table constructed in memory by 
the System Loader. The Jump Table contains all 
references to dynamic segments that may be 
called during execution of the program, 

Kj See kilobyte. 

keyboard equivalent; The combination of the 
Apple key and another key, used to invoke a 
menu item from the keyboard, 

key-down: An event type caused by the user's 
pressing any character key on the keyboard or 
keypad. The character keys include all keys except 
Shift, Caps Lock, Control, Option, and Apple, 
which are called modifier keys. Modifier keys are 
treated differently and generate no keyboard 
events of their own. 

kilobyte (K); A unit of measurement consisting of 
1024 (2 10 > bytes. In this usage, kilo Cfrom the 
Greek, meaning a thousand) stands Tor 1024. 
Thus, 64K memory equals 65,536 bytes. See also 
megabyte. 

kind.- See segment kind. 



language card: Memory with addresses between 
SD000 and $FFFF in any Apple H-family 
computer. It includes two RAM banks in the 
$F>xxx space, called bank-switched memory. The 
language card was originally a peripheral card 
for the 48K Apple II or Apple II Plus that 
expanded the computer's memory capacity to 
64K and provided space for an additional dialec 
of BASIC. 

leading; (Pronounced LED-ing.) The space 
between lines of text. It is the number of pixels 
vertically between the descent line of one 
character and the ascent line of the character 
immediately beneath it. 

length byte: The first byte of a Pascal string. It 
specifies the length of the string, in bytes. 

b'brary (or library file): An object file containing 
program segments, each of which can be used in 
any number of programs. The linker can search 
through the library file for segments that have 
been referenced in the program source file. 

library dictionary segment: The first segment of a 
library file; it contains a list of all the symbols in 
the file together with their locations in the file, 
The linker uses the library dictionary segment to 
find the segments it needs. 

line: In QuickDraw II, the straight-line trajectory 
between two points on the coordinate plane. The 
line is specified by its starting and ending points, 

UneEdil Tool Set; The Apple HGS tool set that 
provides simple text-editing functions. It is used 
mostly in dialog boxes. 

line height: The total amount of vertical space 
from line to line in a text document. Line height 
is the sum of ascent, descent, and leading, 

LinkEd: A command language that can be used to 
control the APW Linker. 

linker: A program that combines files generated 
by compilers and assemblers, resolves all 
symbolic references, and generates a file that can 
be loaded into memory and executed. 
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Lisa: A model of Apple computer; the first 
computer that offered windows and the use of a 
mouse to choose commands. The Lisa is now 
known as the Macintosh XL. 

list: See list control 

list control: A custom control created by the List 
Manager. It is a scrollable, vertical arrangement 
of similar items on the screen; the items are 
selectable by the user. 

list Manager: The Apple IIGS tool set that allows 
an application to present the user with a list from 
which to choose. For example, the Font Manager 
uses the List Manager to arrange lists of fonts. 

load: To transfer information from a peripheral 
storage medium (such as a disk) into main 
memory for use — for example, to transfer a 
program into memory for execution. 

load file: The output of the linker. Load files 
contain memory images that the system loader 
can load into memory, together with relocation 
dictionaries that the loader uses to relocate 
references. 

load segment: A segment in a load file. Any 
number of object segments can go into the same 
load segment. 

local coordinates: A coordinate system unique to 
each GrafPort and independent of the global 
coordinates of the pixel image that the port is 
associated with. For example, local coordinates 
do not change as a window is dragged across the 
screen; global coordinates do not change as a 
window's contents are scrolled. 

local symboL A label defined only within an 
individual segment. Other segments cannot 
reference the label. Compare with global symboL 

Loclnfo: Acronym for location information. The 
data structure (record) that ties the coordinate 
plane to an individual pixel image in memory, 



lock: To prevent a memory block from being 
moved or purged. A block may be locked or 
unlocked by a call to the Memory Manager. 

long (or long word); On the Apple IIGS, a 32-bit 
(4- byte) data type. 

Macintosh: A family of Apple computers; for 
example, the Macintosh 512K and the Macintosh 
Plus. Macintosh computers have high-resolution 
screens and use mouse devices for choosing 
commands and for drawing pictures. 

macro: A single keystroke or command that a 
program replaces with several keystrokes or 
commands. For example, the APW Editor allows 
you to define macros that execute several editor 
keystroke commands; the APW Assembler allows 
you to define macros that execute instructions 
and directives. Macros are almost like higher- 
level language instructions, making assembly- 
language programs easier to write and complex 
keystrokes easier to execute. 

macro library: A file of related macros. 

main event loop: The central routine of an event- 
driven program. During execution, the program 
continually cycles through the main event loop, 
branching off to handle events as they occur and 
then returning to the event loop, 

mainlD: A subfield of the User ID. Each running 
program is assigned a unique mainlD. 

manager: See tool set. 

Mark: The current position in an open file. It is 
the point in the file at which the next read or 
write operation will occur. 

mask; (n) A parameter, typically one or more 
bytes long, whose individual bits arc used to 
permit or block particular features. See, for 
example, event mask, (v) To apply a mask. 

master color value: A 2-byte number that 
specifies the relative intensities of the red, green, 
and blue signals output by the Apple IIGS video 
hardware. 



Glossary 



461 



Lisa: A model of Apple computer; the first 
computer that offered windows and the use of a 
mouse to choose commands. The Lisa is now 
known as the Macintosh XL. 

list: See list control 

list control: A custom control created by the List 
Manager. It is a scrollable, vertical arrangement 
of similar items on the screen; the items are 
selectable by the user. 

list Manager: The Apple IIGS tool set that allows 
an application to present the user with a list from 
which to choose. For example, the Font Manager 
uses the List Manager to arrange lists of fonts. 

load: To transfer information from a peripheral 
storage medium (such as a disk) into main 
memory for use — for example, to transfer a 
program into memory for execution. 

load file: The output of the linker. Load files 
contain memory images that the system loader 
can load into memory, together with relocation 
dictionaries that the loader uses to relocate 
references. 

load segment: A segment in a load file. Any 
number of object segments can go into the same 
load segment. 

local coordinates: A coordinate system unique to 
each GrafPort and independent of the global 
coordinates of the pixel image that the port is 
associated with. For example, local coordinates 
do not change as a window is dragged across the 
screen; global coordinates do not change as a 
window's contents are scrolled. 

local symboL A label defined only within an 
individual segment. Other segments cannot 
reference the label. Compare with global symboL 

Loclnfo: Acronym for location information. The 
data structure (record) that ties the coordinate 
plane to an individual pixel image in memory, 



lock: To prevent a memory block from being 
moved or purged. A block may be locked or 
unlocked by a call to the Memory Manager. 

long (or long word); On the Apple IIGS, a 32-bit 
(4- byte) data type. 

Macintosh: A family of Apple computers; for 
example, the Macintosh 512K and the Macintosh 
Plus. Macintosh computers have high-resolution 
screens and use mouse devices for choosing 
commands and for drawing pictures. 

macro: A single keystroke or command that a 
program replaces with several keystrokes or 
commands. For example, the APW Editor allows 
you to define macros that execute several editor 
keystroke commands; the APW Assembler allows 
you to define macros that execute instructions 
and directives. Macros are almost like higher- 
level language instructions, making assembly- 
language programs easier to write and complex 
keystrokes easier to execute. 

macro library: A file of related macros. 

main event loop: The central routine of an event- 
driven program. During execution, the program 
continually cycles through the main event loop, 
branching off to handle events as they occur and 
then returning to the event loop, 

mainlD: A subfield of the User ID. Each running 
program is assigned a unique mainlD. 

manager: See tool set. 

Mark: The current position in an open file. It is 
the point in the file at which the next read or 
write operation will occur. 

mask; (n) A parameter, typically one or more 
bytes long, whose individual bits arc used to 
permit or block particular features. See, for 
example, event mask, (v) To apply a mask. 

master color value: A 2-byte number that 
specifies the relative intensities of the red, green, 
and blue signals output by the Apple IIGS video 
hardware. 
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master User ID: The value of a User ID, 
disregarding the contents of the auxID field. If an 
application allocates various memory blocks and 
assigns them unique ID's consisting of different 
auxID values added to its own User ID, then all 
will share the same Master User ID and all can be 
purged or disposed with a single call. 

Mb: See megabyte. 

megabyte (Mb): A unit of computer memory or 
disk drive capacity that equals 1,048,576 bytes. 

megahertz (MHz): A unit of measurement of 
frequency, equal to 1,000,000 hertz (cycles per 
second); abbreviated MHz. 



memory block; See block (2). 

memory expansion card: A memory card thai 
increases Apple IIGS internal memory capacity 
beyond 256K, up to 8 megabytes 

memory fragmentation: A condition in which 
free (unallocated) portions of memory are 
scattered because of repeated allocation and 
deallocation of blocks by the Memory Manager. 

memory handle: A number that identifies a 
memory block. A handle is a pointer to a 
pointer— it is the address of a master pointer, 
which in turn contains the address of the block. 

memory Image See Image. 

Memory Manager: The Apple IIGS tool set that 
manages memory use. The Memory Manager 
keeps track of how much memory is available, 
and allocates memory blocks to hold program 
segments or data. 

Memory Segment Table: A linked list in memory, 
created by the loader, that allows the loader to 
keep track of the segments that have been loaded 
into memory. 

menu: A list of choices presented by a program, 
from which the user can select an action. See also 
pull-down menu. 



menu bar: The horizontal strip at the top of the 
screen thai contains menu titles for the pull-down 
menus. 

menu ID: A number in the menu record that 
identifies an individual menu. 

menu line: A line of text plus code characters 
that defines the appearance of a particular menu 
title. 

Menu Manager: The Apple IIGS too! set that 
maintains the pull-down menus and the items in 
the menus. 

m flag: One of 3 flags in the 65816 
microprocessor's Processor Status register that 
controls execution mode, When the m flag is set 
to 1, the accumulator is 8 bits wide; otherwise, it is 
16 bits wide. 

MHz.- See megahertz. 

microprocessor: A central processing unit that is 
contained in a single integrated circuit. The 
Apple IIGS uses a 65816 microprocessor. 

mlnlpalerw: In Super Hi-Res 640 mode, a quarter 
of the color table. Each pixel in 640 mode can 
have one of four colors specified in a 
minipalette. 

Miscellaneous Tool Set: The Apple IIGS tool set 
that includes mostly system-level routines that 
must be available for other tool sets. 

missing symbol: In a font, the symbol substituted 
for any ASCII value for which the font does not 
have a defined symbol. In the Apple IIGS system 
font, the missing symbol is a box containing a 
question mark. 

modal dialog box; A dialog box that puts the 
machine in a state such that the user cannot 
execute functions outside of the dialog box, until 
the dialog box is closed. 

mode: A state of a computer or system that 
determines its behavior. A manner of operating. 
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modeless dialog box: A dialog box that lets the 
user take other action besides responding to the 
dialog box. Compare modal dialog box. 

modification date: An attribute of a ProDOS file; 
it specifies the date on which the content of the 
file was last changed. 

modification time: An attribute of a ProDOS file; 
it specifies the time at which the content of the 
file was last changed. 

Monitor program: A firmware program built into 
the ROM of Apple II computers, used for directly 
inspecting or changing the contents of main 
memory and for operating the computer at the 
machine-language level. 

monospaced: Said of a font whose character 
widths are all identical Compare proportionally 
spaced. 

MOS: Abbreviation for metal-oxide 
semiconductor, a method of fabricating 
integrated-circuits on silicon by using layers of 
silicon dioxide in the make-up of the devices. 
Compare CMOS. 

mouse; A small device that the user moves 
around on a flat surface next to the computer. 
The mouse controls a pointer on the screen 
whose movements correspond to those of the 
mouse. The pointer selects operations, moves 
data, and draws graphic objects. 

mouse button: A button on a mouse device with 
which the user selects objects on Lhc screen. 

mouse-down: An action or an event, signifying 
that the user has pressed the mouse button. 

mouse-up; An action or an event, signifying that 
the user has released the mouse button. 

movable: Able to be moved to different memory 
locations during program execution (a memory 
block attribute), 

native mode: The 1 6-bit operating configuration 
of the 65816 microprocessor. 



NDA: See new desk accessory. 

new desk accessory (NDA): A desk accessory 
designed to execute in a desktop, event-driven 
environment. Compare classic desk accessory. 

newline read mode: A file-reading mode in which 
each character read from the file is compared to 
a specified character (called ihe newline 
character); if there is a match, the read is 
terminated. Newline mode is typically used to 
read individual lines of text, with the newline 
character defined as a carnage return. 

NewWindow parameter list A template 
describing the features of a window that is to be 
created. A pointer to a NewWindow parameter 
list is a required input to the NewWindow call. 

NIL: Pointing to a value of 0. A memory handle is 
NIL if the address it points to is filled with zeros. 
Handles to purged memory blocks are NIL. 
Compare null. 

Note Sequencer: The Apple II GS tool set that 
makes it possible to play music asynchronously 
in programs. 

Note Synthesizer: An Apple HGS tool set that 
facilitates creation and manipulation of musical 
notes, 

null: Zero. A pointer is null if its value is all zeros. 
Compare NIL. 

null event: An event reported when there are no 
other events to report. 

null prefix: A prefix of zero length (and therefore 
nonexistent). 

object file; The output from an assembler or 
compiler, and the input to a linker. It contains 
machine-language instructions as well as other 
information. Also called object program or 
object code. In AP W an object file cannot be 
loaded into memory, Compare source file, load 
file. 
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object module format (OMF): The file format 
used in Apple IlCS object files, library files, and 
load files. 

object segment; A segment in an object file. 

offset: The number of character positions or 
memory locations away from a point of 
reference. 

OK: One of two predefined item ID numbers for 
dialog box buttons (OK ■ 1), Compare Cancel. 

OMF: See object module format 

operating environment The overall hardware 
and software setting within which a program runs. 
Also called execution environment. 

operating system: A general-purpose program 
that organizes the actions of the various parts of 
the computer and its peripheral devices, See also 
disk operating system. 

origin; (1> The first memory address of a 
program or of a portion of one. The first 
instruction to be executed. (2) The location (0,0) 
on the QuickDraw II coordinate plane, in either 
glob ad coordinates or local coordinates. (3) The 
upper-left corner of any rectangle (such as a 
boundary rectangle or port rectangle) in 
QuickDraw II, (4) See character origin. 

oscillator: A device that generates a vibration. In 
the Apple IIGS Digital Oscillator Chip, an 
oscillator is an address generator that points to 
the next data byte in memory that represents 
part of a particular sound wave. 

oval: A circle or ellipse, one of the fundamental 
classes of objects drawn by QuickDraw II. 

overlay: One of a set of program segments meant 
to alternately occupy the same memory space. 
Use of overlays is one way to minimize the 
amount of memory a program needs. 

pack: To compress data into a smaller space to 
conserve storage space. 



page: (1) A portion of memory 256 bytes long 
and beginning at an address that is an even 
multiple of 256. Memory blocks whose starting 
addresses are an even multiple of 256 are said to 
be page-aligned. (2) (usually capitalized) An area 
of main memory containing text or graphic 
information being displayed on the screen, 

page-aligned: Starting at a memory address that 
is an even multiple of 256 (a memory block 
attribute). See page (1). 

palette: The full set of colors available for an 
individual screen pixel. 

parameter: A value passed to or from a function 
or other routine. 

parameter RAM: RAM on the Apple IIGS clock 
chip, A battery preserves the dock settings and 
the RAM contents when the power is off. Control 
Panel settings are kept in battery RAM, 

partial pathname*. A pathname that includes the 
filename of the desired file but excludes the 
volume directory name (and possibly one or 
more of the subdirectories in the path). It is the 
part of a pathname following a prefix — a prefix 
and a partial pathname together constitute a full 
pathname. A partial pathname does not begin 
with a slash because it has no volume directory 
name. 

Pascal: A high-level programming language. 
Named for the philosopher and mathematician 
Blaise Pascal. 

Pascal string; An ASCII character string preceded 
by a single byte whose numerical value is the 
number of characters in the string. Compare C 
string. 

paste: To place the desk scrap (contents of the 
Clipboard — whatever was last cut or copied) at 
the insertion point. 
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patch: To replace one or more bytes in memory 
or in a file with other values. The address to 
which the program must jump 10 execute a 
subroutine is patched into memory at load lime, 
when the System Loader performs relocation on 
a file, 

pathname: A name that specifies a file. It is a 
sequence of one or more filenames separated by 
slashes, tracing the path through subdirectories 
that a program must follow to locate the file. See 
full pathname, partial pathname, prefix, 

pathname prefix: See prefix. 

Pathname Table: A table constructed in memory 

by the System Loader. 'Hie Pathname Table 
contains cross-references between load files 
referenced by number (in the Jump Table) and 
by pathname (in the file directory), 

pattern: (1) An S-by-8 pixel image, used to define 
a repeating design (such as stripes) or color. (2) 
A series of commands to the Note Synthesizer. 

PB register! See program bank register, 

PC register: A register within ihe 65816 
microprocessor that keeps track of the memory 
address of the next instruction to be executed. PC 
stands for program counter. 

pem The conceptual tool with which QuickDraw 11 
draws shapes and characters. Each GrafPort has 
its own pen, 

pen location: The position (on the coordinate 
plane) at which the next character or line will be 
drawn. 

pen pattern: See pattern (1). 

peripheral card: A hardware device placed inside 
a computer, and connected to one of the 
computer's peripheral expansion slots. 
Peripheral cards perform a variety of functions, 
from controlling a disk drive to providing a 
clock/calendar. 

peripheral devices See device. 



phrase: In music synthesis, a set of pointers to 
patterns that make it easy to build repetitive, 
complex passages out of simple patterns. 

picture: A saved sequence of QuickDraw drawing 
commands (and, optionally, picture comments) 
that you can play back later with a single 
procedure call; also, the image resulting from 
these commands. 

pixel: Short for picture element, The smallest dot 
you can draw on the screen. Also a location in 
video memory that corresponds to a point on 
the graphics screen when the viewing window 
includes that location. In the Super Hi-Res 
display on the Apple IIGS, each pixel is 
represented by either two or four bits. See .lso 
pixel Image. , 

pixel image: A graphics image picture consoling 
of a rectangular grid of pixels. 

plain-styled: Said of a font or character that is 
not bold, italicized, underlined, or otherwise 
styled apart from ordinary text. 

plane: Ihe front-to-back position of a window, 
compared to other windows on the desktop. 

point: A unit of measurement for type; 12 points 
equal 1 pica, and 6 picas equal 1 inch; thus, 1 
point equals l hi inch. 

pointer: (1) An item of information consisting of 
the memory address of some other item. For 
example, the 65816 stack register contains a 
pointer to the top of the stack. (2) The mouse 
pointer, an arrow-shaped cursor whose screen 
location is controlled by mouse movements. 

pointing device: Any device, such as a mouse, 
graphics tablet, or light pen, that can be used to 
specify locations on the computer screen. 

polygon: Any sequence of connected lines, 

port: CD A socket on the back panel of the 
computer where the user can plug in a cable to 
connect a peripheral device, another computer, 
or a network. (2) A graphic port (GrafPort). 
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portRect: The GrafPort field lhat defines the 
port's port rectangle. 

port rectangle: A rectangle that describes the 
active region of a GrafPort's pixel map— the part 
that QuickDraw II can draw into. The content 
region of a window on the desktop corresponds 
to the window's port rectangle. 

position-independent: Said of code that can 
execute, without modification of any kind, at any 
location in memory. Compare absolute, 
relocatable 

post; To place an event in the event queue for 
later processing. 

prefix: A pathname starting with a volume name 
and ending with a subdirectory name. It is the 
part of a full pathname that precedes a partial 
pathname— a prefix and a partial pathname 
together constitute a full pathname. A prefix 
always starts with a slash 00 because a volume 
directory name always starts with a slash, 

prefix number; A code used to represent a 
particular prefix. Under ProDOS 16, there are 
nine prefix numbers, each consisting of a 
numeral followed by a slash: 0/, V,...,S/, and V. 

P register: See status register. 

printing loop: The page-by-page cycle that an 
application goes through when it prints a 
document- 
Print Manager: The Apple IIG5 tool set that allows 
an application to use standard QuickDraw II 
routines to print text or graphics on a printer. 

print record: A record containing all the 
information needed by the Print Manager to 
perform a particular printing job. 

private scrap; A buffer (and its contents) set up 
by an application for cutting and pasting, 
analogous to but apart from the desk scrap. 

private symbol; A label in a segment that may be 
referenced by other segments in the same file, 
but not by segments in other files. 



processor status register; See status register. 

ProDOS: A family of disk operating systems 
developed for the Apple II family of computers. 
ProDOS stands for Professional Disk Operating 
System, and includes both ProDOS 8 and 
ProDOS 16. 

ProDOS 8: A disk operating system developed foi 
standard Apple II computers. It runs on 6502- 
series microprocessors and on the Apple lies 
when the 65816 processor is in 6502 emulation 
mode. 

ProDOS 16: A disk operating system developed 
for 65816 native-mode operation on the Apple 
IICS. It is functionally similar to ProDOS B but 
more powerful, 

program bank register: The 65816 register whose 
contents form the high-order byte of all 3-byte 
code address operands. 

program counter: See PC register. 

program status register: See status register, 

proportionally spaced: Said of a font whose 
characters vary in width, so the amount of 
horizontal space needed for each character is 
proportional to its width. Compare monospaced. 

puU-down menu; A set of choices for actions thai 
appears near the top of the display screen in a 
desktop application, usually overlaying the 
present contents of the screen without disrupting 
ihcm, Dragging through the menu and releasing 
the mouse button while a command is 
highlighted chooses that command. 

purge: To temporarily deallocate a memory 
block. The Memory Manager purges a block by 
setting its master pointer to NIL (0). All handles 
to the pointer are still valid, so the block can be 
reconstructed quickly. Compare dispose. 
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purge level; A memory block attribute, indicating 
that the Memory Manager may purge the block if 
it needs additional memory space. Purgeable 
blocks have different purge levels, or priorities 
for purging; these levels are set by Memory 
Manager calls. 

queue; A list in which entries are added at one 
end and removed at the other, causing entries to 
be removed in first-in, first-out (FIFO) order. 
Compare stack. 

QuickDraw II: The Apple IIGS tool set that 
controls the graphics environment and draws 
simple objects and text. Other tools call 
QuickDraw II to draw such things as windows. 

QuickDraw n Auxiliary: An Apple IIGS tool set 
that provides extensions to the capabilities of 
QuickDraw n. 

quit: To terminate execution in an orderly 
manner. Apple IIGS applications quit by making a 
ProDOS 16 QUIT call or the equivalent. 

quit return stack; A table, maintained in memory 
by ProDOS \6, that contains the User ID'S of 
programs that want to be reexecuted after the 
current program quits. 

radio buttons A common type of control in 
dialog boxes. Radio buttons are small circles 
organized into families — clicking any button on 
turns off all the others in the family, like the 
buttons on a, car radio. 

RAM; See random-access memory. 

random- access memory (RAM); Memory in 
which information can be referred to in an 
arbitrary or random order. Programs and other 
data in RAM are lost when the computer is 
turned off, (Technically, the read-only memory 
(ROM) is also random access, and what's called 
RAM should correctly be termed read-write 
memory?) Compare read-only memory. 



read-only memory (ROM): Memory whose 
contents can be read, but not changed; used for 
storing firmware. Information is placed into ROM 
once, during manufacture; it then remains there 
permanently, even when the computer's power is 
turned off. Compare random- access memory. 

rectangle: One of the fundamental shapes drawn 
by QuickDraw II. Rectangles are completely 
defined by two points- — their upper-left and 
lower-right corners on the coordinate plane. The 
upper-left corner of any rectangle is its origin, 

reentrant: Said of a routine that is able to accept 
a call while one or more previous calls to it are 
pending, without invalidating the previous calls. 
Under certain conditions, the Apple IIGS 
Scheduler manages execution of routines that are 
not reentrant. 

region: An arbitrary area or set of areas on the 
QuickDraw coordinate plane. The outline of a 
region must be one or more closed loops. 

RELOAD segment: A segment that is always 
reloaded from disk when a program is executed, 
even if the program is in a dormant state in 
computer memory. Some programs require 
RELOAD segments in order to be restartable, 

relocatable: Characteristic of a. load segment or 
other OMF program code that includes no 
references to specific address, and so can be 
loaded at any memory address. A relocatable 
segment consists of a code image followed by a 
relocation dictionary. Compare absolute. 

relocation: The act of modifying a program in 
memory so that its address operands correctly 
reflect its location and the locations of other 
segments in memory. Relocation is performed by 
the System Loader when a relocatable segment is 
first loaded into memory. 

relocation dictionary: In object module format, a 
portion of a load segment that contains 
relocation information necessary to modify the 
memory image portion of the segment. See 
relocadorL 
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resource? A type of organization for certain 
components of Macintosh files. Resources 
provide a convenient means for manipulating 
the fixed (unchanging) parts of a program file. 

resource editor.- A program for editing resources, 
especially data in a program, without having to 
recompile the program. 

Resource Manager: The Macintosh toolbox 
component that retrieves, manipulates, and 
disposes of resources. 

restart! To reactivate a dormant program in the 
computer's memory. The System Loader can 
restart dormant programs if all their static 
segments are still in memory, If any critical part 
of a dormant program has been purged by the 
Memory Manager, the program must be reloaded 
from disk instead of restarted. 

restartable: Said of a program that reinitializes its 
variables and makes no assumptions about 
machine state each time it gains control. Only 
restartable programs can be resurrected from a 
dormant state in memory. 

RGB; Abbreviation for red-green-blue, a. method 
of displaying color video by transmitting the 
three primary colors as three separate signals. 
There are two ways of using RGB with computers: 
TO RGB, which allows the color signals to take 
on only discrete values; and analog RGB, which 
allows the color signals to take on any values 
between their upper and lower limits. 

ROM: See read-only memory- 
routine: A part of a program that accomplishes 
some task subordinate to the overall task of the 
program. 

RTL Return from Interrupt, a 65816 assembly- 
language instruction. 

RTL: Return from Subroutine (Long), a 65816 
assembly-language instruction. 

RTS: Return from Subroutine, a 65816 assembly- 
language instruction. 



SANE; See Standard Apple Numeric 

Environment. 

SANE Tool Set: The Apple IIGS tool set that 
performs high-precision floating-point 
calculations, following SANE standards. 

scaled font! A font that is creaLed by the Font 
Manager by calculation from a real font of a 
different size. 

scan line; A single horizontal line of pixels on 
the screen. It corresponds to a single sweep of 
the electron gun in the video display tube. 

scanllne control byte (SCB): A byte in memory 
that controls certain properties, such as available 
colors and number of pixels, for a scan line on 
the Apple IIGS. Each scan line has its own SCB. 

Scheduler; The Apple IIGS tool set that manages 
requests to execute interrupted software that is 
not reentrant. If, for example, an interrupt 
handler needs to make system software calls, it 
must do so through the Scheduler because 
ProDOS 16 is not reentrant. Applications 
normally need not use the Scheduler because 
ProDOS 16 is not in an interrupted state when it 
processes applications' system calls, 

Scrap Manager: The Apple IIGS tool set that 
supports the desk scrap, which allows data to be 
copied from one application to another (or from 
one place to another within an application). 

scroll: To move an image of a document or 
directory in its window so that a different part of 
it becomes visible, 

scroll bar: A rectangular bar that may be along 
the right side or bottom of a window. Clicking or 
dragging in the scroll bar causes the view of the 
document to change. 

segment; A component of an OMF file, consisting 
of a header and a body. In object files, each 
segment incorporates one or more subroutines. 
In load files, each segment incorporates one or 
more object segments, 
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segment kinds A numerical designation used to 
classify a segment in object module format 

self- booting: Said of a program that executes 
automatically when the computer is turned on or 
reset. 

sequence: A series of commands that tells the 
computer what notes to play and when. 

serial Interface? A standard method, such as RS- 
232, for transmitting data serially (as a sequence 
of bits). 

serial port: The connector for a peripheral 
device that uses a serial interface, 

Shaston: The Apple IIGS system font. 

shell: A program that provides an operating 
environment for other programs, and that is not 
removed from memory when, those programs are 
running, For example, the APW Shell provides a 
command processor interface between the user 
and the other components of APW, and remains 
in memory when APW utility programs are 
running. A shell is one type of controlling 
program. 

shell application; A type of program that is 
launched from a shell and runs under its control, 
Shell applications are ProDOS 16 file type $B5 
In APW, compilers and certain Shell commands 
are shell applications that are launched from the 
APW Shell. 

shell calls A request from a program to the APW 
Shell to perform a specific function. 

shut down; To remove from memory or 
otherwise make unavailable, as a tool set that is 
no longer needed or an application that has quit. 

size box: A small square in the lower-right corner 
of some windows, with which the user can resize 
the window, The size box corresponds to the 
grow region, 

65C816: The version of the 65816 microprocessor 
used in the Apple IIGS. The 65C816 is a CMOS 
device. 



65816: A general term for the type of 
microprocessor used in the Apple IIGS. The 
65816 is related to, but more advanced than, the 
6502 microprocessor. It has a 1 6-bit data bus and 
a 24 -bit address bus. 

65816 assembly language: A low-level 
programming language written for the 65816 
family of microprocessors. 

6502: The microprocessor used in the Apple II, in 
the Apple II Plus, and in early models of the 
Apple He, The 6502 is an NMOS device with an 8- 
bit data bus and a l6-bit address bus. 

640 mode: An Apple IIGS video display mode, 
640 pixels horizontally by 200 pixels vertically. 

slot: A narrow socket inside the computer where 
the user can install peripheral cards. Also called 
an expansion slot. 

SmartPorts A set of firmware routines supporting 
multiple devices connected to the Apple IIGS disk 
port. 

software; A collective term for programs, the 
instructions that tell the computer what to do. 
Software is usually stored on disks. Compare 
firmware, hardware. 

Sound Tool Set The Apple lies tool set that 
provides low-level access to the sound hardware. 



source; See source location. 

source file: An ASCII file consisting of 
instructions written in a particular language, such 
as Pascal or assembly language. An assembler or 
compiler converts source files into object files. 

source location; The location (memory buffer or 
portion of the QuickDraw II coordinate plane) 
from which data such as text or graphics are 
copied. Compare destination location. See also 
source rectangle 1 . 

source rectangle: The rectangle (on the 
QuickDraw II coordinate plane) from which text 
or graphics are taken when transferred 
somewhere else. Compare destination rectangle. 
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special memory: On an Apple IIGS, all of banks 
$00 and $01, and all display memory in banks 
$E0 and $E1 . It is ihe memory directly accessed 
by standard-Apple n programs running on the 
Apple IIGS. 

spool printing: A two-step printing method used 
to print graphics on the ImageWrher. In the first 
step, it writes out (spools) a representation of 
your document's printed image to a disk file or 
to memory. In the Second step, this information 
is converted into a bit image and printed. 
Compare draft printing, 

S register: See stack register. 

stack: A list in which entries are added (pushed) 
and removed (pulled) at one end only (the top 
of the stack), causing them to be removed in last- 
in, first-out (UFO) order. The stack usually refers 
to the particular stack pointed to by the 658l6's 
stack register. Compare queue. 

stack pointer: See stack register. 

stack register: A register in the 65816 processor 
that indicates the next available memory address 
in the stack. 

Standard Apple Numerics Environment 

(SANE): The set of methods that provides the 
basis for floating-point calculations in Apple 
computers, SANE meets all requirements for 
extended-precision, floating-point arithmetic as 
prescribed by IEEE Standard 754 and ensures 
that all floating-point operations arc performed 
consistently and return the most accurate results 
possible, 

standard Apple II: Any computer in the Apple II 
family except the Apple IIGS. lliat includes the 
Apple II, the Apple II Plus, the Apple lie, and the 
Apple lie. 

Standard File Operations Tool Set: The Apple 
IIGS too! set that creates a standard user interface 
for opening and closing files. 



standard linker (APW): One aspect of the linker 
supplied with APW. The operation of the 
standard linker is automatic. Compare advanced 
linker. 

standard window parts.- The window features that 
allow the user to scroll through the data in the 
window, change the window's shape, or close the 
window. They also provide information about the 
document currently displayed in the window. 

START: The name of the program in the 
SYSTEM /subdirectory of the startup disk that is 
launched automatically when the system is 
booted. STAIIT is typically a finder or program 
launcher. 

stan up; To get the system or application 
program running. 

static segments A program segment that must be 
loaded when the program is started, and cannot 
be removed from memory until execution 
terminates. Compare dynamic segment. 

static text: Text on the screen that cannot be 
altered by the user. 

status register: A register in the 65816 
microprocessor that contains flags reflecting the 
various aspects of machine state and operation 
results. 

string: A sequence of characters. See C string, 
Pascal string, 

structure region; An entire window; its content 
region plus its frame region. 

Style dialog box; A dialog box that allows the 
user to specify formatting information, page sire, 
and printer options. 

styled variation: An italicized, boldfaced, 
underlined, or otherwise altered version of a 
plain-styled character or font. 

subdirectory: A file that contains information 
about other files. In a hierarchical file system, 
files are accessed through the subdirectories that 
reference them. 
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subroutine: A part of a program that can be 
executed on request from another point in the 
pro^m \nd that, upon completion, returns 
control to the point of the request. 

Suoer Hl-Re SI E,ther of two high-resolution Apple 
uTLpU -odes. 320 mode consists of an 
array of pixels 320 wide by 200 high, with 1 6 
avTble'colors, 640 mode is an array 640 wide 
by 200 high, with 16 available colors (with 
restrictions). 

switcher: A controlling program that rapidly 
transfers execution among several applications. 
switch event An event type reserved for future 
uTsuch as in conjunction with a switcher. 
sycuboUc reference: A name or label, such as the 
ZTof a subroutine, that is used to refer • » a 
Lation in a program. When a P"*"™ * ^ 
3l symbolic references are resolved: whence 
program is loaded, actual memory addresses are 
patched into the program to replace the 
symbolic references. (This process Is called 
relocation.) 



svntheslzer: CO A hardware device capable of 

S5j sound digitally and converting « into an 

analoR waveform that you can hear. W ay 

analogy, any sound-making entity, such as the 

Note Synthesizer tool set- 

svstem disks A disk that contains the operating 

^eTand other system software needed to run 

applications. 

svstem event mask; A set or flags that control 

wSTe'nt types get posted into the event queue 

by the Event Manager. 

system failure: The unintentional termination of 

^ogC execution due to a severe software error. 

Svstem Failure Manager: A part of the 
Saneous Tool Set that processes fatal errors 
by displaying a message on the screen and 
halting execution. 



system fUe level: A ^'^ n *^*t£j 
associated with each open ProDOS 16 file Every 

assigned to them. By manipulating the system _iiks 
£3 a controlling program can easily close or 
flush files opened by its subprograms. 
system folder: The SYSTEM/subdirectory on a 

ProDOS 16 system disk. 

svstem library prefix ProDOS 16 prefix number 

S^dSk directory containing library 

files used by system software. 

the Memory Manager. 
system menu bar: The menu bar that always 
aToears at the top of the screen in desktop 
^ons. u contains ail of *-— d 
used functions, in menus such as File, mk, an 

on. 



system prefix (ProDOS 8> The one prefix 

maintained by ProDOS 8. 

system software: The components of a computer 

SSL that support application programs by 

managing system resources such as memory and 

I/O devices. 

system window: A window in which a desk 

accessory is displayed. 

task code: A numeric value assigned id the result 

^each event handled by TaskMaster. Compare 

event code. 

task mask: A parameter passed to TaskMaster 

^cS which types of events TaskMaster ,s to 

respond to. 
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TaskMaster: A Window Manager routine that 
handles many typical events for an application. 
Applications may call TaskMaster instead of 
CetNextEvent 

template: A data structure or set of parameters 
that defines the characteristics of a desktop 
Feature, such as a window or control. The 
NewWindow parameter list is a template that 
defines the appearance of a window to be 
opened by the NewWindow call. 

text-based Interface! An interface between 
computer and user in which all screen drawing 
(or other output) consists of characters. The form 
of each character is stored in ROM and can be 
involved with a single byte of data. Compare 
graphic Interlace. 

text buffer: A I-bit-per-pixel pixel image reserved 
for the private use of the QuickDraw II text- 
drawing call. 

text file: A file consisting of the ASCII 
representau'on of characters. 

text mode: One of 16 possible interactions 
between pixels in text being drawn to the screen 
and pixels on the screen that fall under 
characters being drawn. Compare drawing mode. 

Text Tool Set An Apple HCS tool set that 
provides an interface between Apple II character 
device drivers and applications running in native 
mode. 

320 mode: An Apple 1IGS video display mode, 
320 pixels horizontally by 200 pixels vertically. 

tick count* The (approximate) number of 60th 
second intervals since system startup, 

title bar: The horizontal bar at the top of a 
window that shows the name of the window's 
contents. The user can move the window by 
dragging the tide bar. 

tooL See tool set 



toolbox: The collection of built-in routines on 
the Apple IIGS that programs can call to perform 
many commonly needed functions. Functions 
within the toolbox are grouped into tool sets. 

tool calk A call to a function within a tool set. 

Tool Locator: The Apple IIGS tool set that 
dispatches tool calls. The tool locator knows and 
retrieves the appropriate routine when you make 
a tool call. 

Tool Pointer Table fTPT)- A table, maintained by 
the Tool Locator, that contains pointers to all 
active tool sets. 

tool set: A group of related routines (usually in 
ROM) that perform necessary functions or 
provide programming convenience. They are 
available to applications and system software. 
The Memory Manager, the System Loader, and 
QuickDraw II are Apple IIGS tool sets. 

tool table: A list of all needed tool sets and their 
minimum required versions. An application 
constructs this table in order to load its RAM- 
based tool sets with the LoadTools call. 

track: (1) One of a series of concentric circles 
magnetically recorded on the surface of a disk 
when it is formatted. Each track is further divided 
into sectors. Each sector can hold several K of 
data. (2) A grouping of items in a musical 
sequence. The Note Sequencer supports multiple 
tracks to facilitate writing multi-instrument music. 

transfer mode; A specification of which Boolean 
operation QuickDraw should perform when 
drawing. See, for example, XQR. 

TRUE: Nonzero. The result of a Boolean 
operation, Opposite of FALSE. 

TTL RGB: A type of color video consisting of 
separate red, green, and blue signals that can 
have only discrete values. 
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typelD: A subfield of the User ID. The User ID 
Manager assigns a typelD value based on the 
type of program (application, tool set, and so 
on) requesting the memory. 

unhighlighu To restore to normal display. 

Selected controls, menu items, or other objects 

may be highlighted (usually displayed in inverse 

colors) while in use, and unhighlighied when not 

in use. 

unload: To remove a load segment from 

memory. To unload a segment, the System 

Loader does not actually "unload" anything; it 

calls the Memory Manager to either purge or 

dispose of the memory block in which the code 

segment resides. 

unlock: To permit the Memory Manager to move 

or purge a memory block if needed. Opposite of 

lock, 

immovable See fixed. 

unpack: To restore to normal format from a 

packed formal. 

unpurgeablej Having a purge level of zero. The 
Memory Manager is not permitted to purge 
memory blocks whose purge level is zero. 

updatei A type of window event, signifying that all 
or part of the window needs to be redrawn. 

update event; An event posted by the Window 

Manager when all or part of a window needs to 

be redrawn. 

update region: A description of the part of a 

window that needs to be redrawn. The Window 

ManagcT keeps track of each open window's 

update region. 

User ID: An identification number that specifies 

Ihe owner of every memory block allocated by 

the Memory Manager. User ID's are assigned by 

the User ID Manager. 



User ID Manager: A part of the Miscellaneous 

Tool Set that is responsible for assigning User 

ID's to every block of memory allocated by the 

Memory Manager. 

vector: A location that contains a value used to 

find the entry point address of a subroutine. 

vertical blanking: The interval between successive 

screen drawings on a video display. It is the time 

between drawing the last pixel of the last scan 

line of one frame and the first pixel of the first 

scan line of the next frame. 

visible region: The part of a window that's 

actually visible on the screen. The visible region 

js a GrafPort Held manipulated by the Window 

Manager. 

voice: Any one of l6 pairs of oscillators in the 

Ensoniq sound chip on the Apple 1ICS. 

volume name: The name of the volume directory. 

wedge: A filled arc, one of the fundamental 
shapes drawn by QuickDraw II. 

window: A rectangular area that displays 
information on a desktop. You view a document 
through a window. You can open or close a 
window, move it around on the desktop, and 
sometimes change its size, scroll through it, and 
edit its contents. The area inside the window's 
frame corresponds to the port rectangle of the 
windows GrafPort. 

window frame: The outline of the entire window 
plus certain standard window controls. 
Window Manager: The Apple IIG5 tool set that 
updates and maintains windows. 
window menu bar: A menu bar that appears at 
the top of the active window, below the system 
menu bar. Window menu bars can contain 
document titles, applications, and functions. 

window record; The internal representation of a 
window, where the Window Manager stores all the 
information it needs for its operations on that 
window. 
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word- On the Apple IICS, a 16-bit (2-byle) data 
type. Compare long word. 

x flag: One of three /lag bits in the 65816 
processor that programs use to control the 
processor's operating modes. In native mode, the 
setting of the x flag determines whether the index 
registers are 8 bits wide or 16 bits wide. See also 
e flag and m flag, 

XORi Ex elusive -OR. A Boolean operation in 
which the result is TRUE if, and only if, the two 
items being compared are unequal in value. 

X register; One of the two index registers in the 
65816 microprocessor. 

T register: One of the two index registers in the 
65816 microprocessor. 

zero page: The first page (256 bytes) of memory 
in a standard Apple II computer Cor in the Apple 
TIGS when running a standard Apple II program). 
Because the high-order byte of any address in 
this part of memory is zero, only a single byte is 
needed to specify a zero-page address. Compare 
direct page. 

zoom box: A small box with a smaller box 
enclosed in it, found on the right side of the title 
bar of some windows. Clicking the zoom box 
expands the window to its maximum size; clicking 
it again returns the window to its original size. 

zoom area: The window sub region that 
corresponds to the zoom box. 
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Here are four categories of books that can help you learn more 
about desktop programming on the Apple IIGS. We list only a few 
titles in each category; many more books are available. 

Several of the books listed below are part of the Apple IIGS 
technical suite. See "Introduction to the Programmer's 
Introduction" for other titles in the suite. 



Apple IIGS technical manuals 

In this category, the most important book for writing programs is 
the toolbox reference manual, You cannot write desktop 
applications without it, 

Apple IIGS Firmware Reference. Reading, Mass.: Addis on- Wesley, 
1987. 

Apple IIGS Hardware Reference, Reading, Mass.: Addison-Wcslcy, 
1987. 

Apple IIGS ProDOS 16 Reference. Reading, Mass.: Addison-Wcsley, 
1987. 

Apple IIGS Toolbox Reference, Volumes 1 and 2. Reading, Mass.: 
Addison-Wesley 1987. 

Technical Introduction to the Apple IIGS. Reading, Mass.: 
Addison- Wesley 1986. 
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Programming manuals 

This category includes both books and development 
environments. APW (Apple IIGS Programmer's Workshop) is 
essential if you plan to compile and modify HodgePodge. The 
usefulness of the other books depends on which language(s) you 
are programming in. This list is by no means complete: 
additional books for these and other Apple IIGS programming 
languages are available, 

* APDA; Books marked lAPDAf are distributed through the 
Apple Programmer's and Developer's Association. See 
Chapter 9. 

Apple IIGS Programmer's Workshop Assembler Reference. 
Cupertino, Calif.: Apple Computer, Inc., 1987. [APDA] 

Apple IIGS Programmer's Workshop C Reference. Cupertino, 
Calif.: Apple Computer, Inc., 1987.' [APDA] 

Apple IIGS Programmer's Workshop Reference. Cupertino, Calif.: 
Apple Computer, Inc., 1987.' [APDA J 

Eyes, David, and Ron Lichty. Programming the 65816, Including 
the 6502, 65C02, and 65802. New York: Prentice Hall Press, 1986, 

Jensen, Kathleen, and Niklaus Whth. Pascal User Manual and 
Report. 3rd.ed. New York: Springer- Verlag, 1982. 

Kernighan, Brian W., and Dennis M. Ritchie. The C Programming 
Language. Engelwood Cliffs, N, J. : Prentice-Hall, 1978. 

ORCA/ Pascal: A Pascal Compiler and Development System for 
the Apple IIGS. Albuquerque, N. M. : The Byte Works, Inc., 1987.* 

TML Pascal for the Apple IIGS.- User's Guide and Reference 
Manual (APW version). Jacksonville, Fla.: TML Systems, Inc., 
1987.' 

* Includes software. 
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All-Apple manuals 

Here nole especially the Human Interface Guidelines book^it 
contains a wealth of information to help you design your program 
for maximum effectiveness and ease of use. 
Apple Numerics Manual. Reading, Mass.: Addison-Wesley, 1987. 
Human Interface Guidelines: Tl)e Apple Desktop Interface. 
Reading, Mass.: Addison-Wesley, 1987. 



Macintosh programming manuals 

These books are included because many desktop concepts, 
although developed originally for the Macintosh, are directly 
applicable to the Apple IIGS, Remember, though, thai details of 
implementation are often quite different! 

Chernicoff, Stephen. Macintosh Revealed. Volume One.- Unlocking 
the Toolbox. Hasbrouck Heights, N. J.: Hayden Book, 1985 

Chernicoff, Stephen. Macintosh Revealed. Volume Two: 

Programming With the Toolbox. Hasbrouck Heights, N. J.-. 

Hayden Book, 1985. 
Inside Macintosh, Volumes I-V. Reading, Mass.: Addison-Wesley, 

1987, 
Programmer's Introduction to the Macintosh Family. Reading, 

Mass.: Addison-Wesley, 1988. 
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"About..." dialog boxes 31, 

142-144 
"About Hodgepodge" dialog box 

39 
absolute code 24, 196, 226-227, 

295 
vs, relocatable code 24, 227 

access byte 215 

accessing Files 162-165 

accumulator 4, 66, 294 

action routine CNDA> 265 

activate events 68, 69, 72, 73 

activateEvt 69 

activating 73 

active controls 128, 129 

active windows 114-116 

AddToMenu 55, 59, 120, 154, 305, 

306 
AdjWind 57,59, 155 
advanced linker (APW) 223, 235, 

236 
alert box 135 

default button 135 
template for creating 140 
alerts 135-136 
Caution Alert 135 
Fipte Alen 155 
programming techniques 141 
sound in 135 
Stop Alert 135 
alert windows 110, 111, 116, 136 
ALLOCJNTERRUPT 272 
Alternate Display Mode 157 
APDA (Apple Programmer's and 
Developer's Association) xix, 
35, 224, 278 



applEvt 69 

Apple Certified Developer 

278-27? 
Apple Desktop Bus 2, 8, 21, 174 
Apple Desktop Bus Tool Set 21, 

174 
Apple menu 31, 47, 75, 147 
Apple Programmer's and 
Developer's Association 
CAFDA) xtx, 35, 224, 278 
AppleTalk 2, 8, 9, 167 
Apple 11 13, 21 

defined xxt 
Apple He xxi, 7, 8. 13, 290 
Apple lie xxi, 7-9, 13, 174, 290 
Apple UGS. See also ProDOS 8; 
ProDOS 16; programming 
techniques 
built-in I/O 8-9 
clock-calendar 9 
clock speeds 4 
compatibility wiih standard Apple 

II 9-10, 291-292 
Control Panel 9 
disk port 8 
execution modes 4 
Firmware xviii 
game I/O connectors 2, 8 
general xm-xxii, 2-27 
hardware xvii 
keyboard 2, 8 
memory 2, 4, 3-6 
microprocessor 2, 3-5 
programming (general) xvii 
registers 4 

serial I/O ports 2, 8, 9 
slots 2, 6, 8^9 



sound 2, 8, 174 
video 2, 6-7 
Apple IICS Debugger 224. 

24S-253 
Apple HGS Programmer's 

Workshop (APW) xvlil, 26-27, 
65, 205, 220-225, 296 
advanced linker 223, 235, 236, 

238 
assembler xviii, 222 
C compiler xviii, 222 
editor 222 

language considerations 225 
linker 222 

parameter- passing 225 
program descriptions 221-224 
Shell 199. 221-222, 259, 261 
standard linker 223, 235, 238 
utilities 223 

Compact 223 
Crunch 223 
DumpOHJ 223 
Equal 224 
Files 224 
Inil 224 
MacGen 224 
MakeLib 224, 238 
Search 224 
Apple IIGS Tbofbox xvfrf, 17-22. 
42. 62-106, 108-144, 
146-183 See also tool sets or 
specific routine/cool set 
calls (typographic convention for) 

xxii, 36 
compared to Macintosh 284—289 
constants 38 
data structures 38 
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errors 65, 66, 67 
macros 65 

memory requirements 5 
Apple II Plus xxi, 8, 9, 290 
application-defined events 69, 73 
application prefix 209 
applications 256-259 
hybrid 292-293 
programming techniques 26, 

228-229, 256-259 
restartable 259 
self-booting 257-258 
application system disk 3OO-30 1 
application windows 111 
APW. See Apple II GS 

Programmer's Workshop 
arc (QuickDraw II) 87, 91 
ascent/ascent line 93 
AskUser 59, 121, 163, 211, 306 
assembler (APW) xvtii, 222 
assembly language xiv, 4, 65, 225, 
234 
Hodge Podge and 65-66, 190. 

202, 311-376 
programming examples 190, 
193. 239-246, 263. 265, 
311-376 
programming techniques 4, 

283-284, 290 
typographic convention for xxii 
attrAddr 187 
attrBank 187 
attrFixed 187 
attributes word 188 
attrLocked 187 
attrNoCross 187 
AttrHoSpec 187 
attrPage 167 
attrPurge 187 
auto-key events 69, 71-72 
autoKeyEvt 69 
auxJD field 192-194 
auxiliary type field (ProDOS) 217 
auxiliary type file attributes 217, 
218 



background colors 92 
background pattern 85 



background pixels 93 
background procedure 173 
backup bit 215 
bank -boundary limited 187 
banks. See memory banks 
bank zero 4, 6, 192, 203, 248, 

267-270, 293-296 
base line 93 
batch mode 13 
Battery RAM routines 181 
BcginUpdate 115. 118, 134 
bit images 286 

bit planes 98 

black and white drawing, QuickDraw 
II 103 

blocks. See memory blocks 

boot prefix 209 

bottom scroll bar 110 

boundary rectangle 80-84, 103 

boundsHect 80 

breakpoints, (debugging) 250-251 

built-in interrupt handler 267 

built-in I/O 2, 8-9 

Busy Rag 157, 182, 183 

buttons 125, 128, 132-135 



CalcMenuSize 154, 155, 165 
Cancel button 132, 133, 139 
carry bit. See c flag 
Caution Alert 135 
C compiler (APW) xviii, 222 
CDA, See classic desk accessory 
Certified Developer 278-279 
cflag 66 
CHANGE_PATH 214 

character devices 173 

character image 93 

character origin 93 

characters 92, 93-94 

character width 93 

check boxes 125, 128 

checkDiskError 136, 140, 
308-310 

CheckFrontW 50, 116 

checkToolError 46,306-307 

ChooseFont 97 

Choose Printer command (File 
menu) 32, 166, 289 



Chooser 167, 289 
chunky pixel organization 98 
circles 90 

C language xiv, xvlil, 65, 202, 225, 
230, 234, 259 
HodgePodge and 377-412 
programming examples 190, 
377-412 
classic desk accessory, 

programming examples 263 
classic desk accessory (CDA) 156, 
247, 262, 300. See also desk 
accessories; new desk 
accessory 
supporting 157 
writing 263 
CLEAR„BACKUP_BIT 215 
Clear command (Edit menu) 32 
clicking (mouse) 14, 15, 48, 110 
Clipboard 32, 92, 159, l60. l6l 
clipping 77, 81-82, 83, 105, 136 
clipping region 81, 82, 84 
clipRgn 82 
clock-calendar 9 
clock (microprocessor) 9 
clock (real-time) 9 
clock routines 181 
clock speeds 4, 269, 271, 290 
CLOSE 210, 211, 213 
close box 48, 110, 111, 114 
Close command (File menu) 32 
Close Dialog 134, 144 
CloseNDA 158 
CloseNDAbyWinPtr 57, 158 
ClosePort 97 
close routine (NDA) 265 
CloseWindow 57, 114 
closing files 210 
color palette 7, 99-100 
colors 98-103 
dithered 101-103 
QuickDraw II 98-103 
Super Hi-Res 7, 98 
window frame 111 
color tables 7, 99-100 
command-line interface 13 
commands. See specific command 
compaction 188 
Compact utility (APW) 223 
compatibility (Apple II) 9-iQ 



480 



Index 



compiler xviil, 222 

complete system disk 298-300 

constants 

event codes 69 

memory-block attributes 137 

task codes 74 
toolbox-defined 38, 50 
constructing menus 149-152 
content region 112, 114, 129 
control action procedure 118 
Control-Apple-Escape 73 
control definition procedure 130 
controlling programs 197, 199, 

259-260 
controlling user access to files 218 
Control Manager 20, 64, 71, 117, 

124-131, 158, 264 288 
control manipulation (Hodgepodge) 

130 
Control Panel 9, 157, 174 
control-related events, 

programm ing techn iques 1 29 
controls 20, 116, 117, 124-131 
active 128, 129 
custom 130 
events and 129-130 
frame 129 
highlighting 128 
inactive 128 
invisible 128 
types of 124-125 
value 125, 128, 130 
windows and 129 
coordinate plane 76, 77-79, 80 
locations on 78 
size of 77 
coordinates 

global 70, 77, 82-84 
local 77, 82-34, 103, 105, 
117-118 
Copy command (Edit menu) 32, 

141, 159, 160 
COPY mode 87 
Copy Pixels 103 
CREATE 210, 213 
Crunch utility CAPW) 223 

C strings 92, 287 
CuShutDown 58 
CUStaitUp 45 
cursor 1 16 



cursor keys 8 

custom controls 130 

custom menus 149 

custom windows 111 

Cut command (Edit menu) 32, 

141. 159, 160 
cutting and pasting 159-161 

internally 160 

large amounts of data l6l 

private scrap 161 

programming techniques 
160^161 

publicly 160 



data area 105, 112, 117 
Data Bank register 294, 295 
data structures 277 

initializing (Hodgepodge) 38-41 
toolbox-defined 38 
DEALLOCJNTERKUPT 272 
debugging 246-254 

with Apple IIGS Debugger 

248-253 
with desk accessories 246-247 
with Monitor program 247-248 
default button 
alert box 135 
dialog boxes 139 
default prefix 208, 209 
default properties (windows) 108 
definition procedures 51, 109, 130, 

136, 149 
delete 141 
DeleieMltem 154 

Deref 190 

dereferencing 189, 190 
desceni/desceni line 93 
desk accessories 21, 47, 75, 

156-158, 182. See also classic 
desk accessory; new desk 
accessory 
Apple menu and 31 
debugging with 246-247 

246-247 
HodgePodge and 158 
Macintosh 156, 289 
programming techniques 
262-265 



supporting 156-158 
TaskMaster and 158 
writing 262-265 
desk-accessory event 69 

aesHACCEvt 69 

Desk Manager 21, 47, 64, 71, 

156-158, 182. 262-265 
desk scrap 21, 141, 159 
data types 1 60 
on disk 160 
DeskShutDown 58, 158 
DeskSurtUp 45, 158 
desktop, programming techniques 

10 
desktop applications 10, 13, 124 
desktop features, supporting ■ 

156-161 
desktop interface xviii, xix-xx, 

10-13, 20-21, 257 
desktop-interface tool sets 20-21 
DESTROY 210, 213 
destroying files 210 
Developer Technical Support 279 
device-driver events 69, 73 
device drivers 69, 166, 173 
device independence 12 
device-interface tool sets 21 
DIftLOG.ASM 353-360 
dialog boxes 21, 131-136 
default button 139 
message 135 
modal 133, 139 
modeless 133, 136 
DIALOG.CC 400-404 
dialog items 137-140 

defining with a template 140, 

285 
disabling 138 
display rectangle 137, 139 
inactive controls as 138 
invisible 138 
item ID 137, 139 
item type 137. 138 
Dialog Manager 21,116,131-144. 

308 
DIALOG, pas 429-433 
dialog records 137 
dialogs, programming techniques 

141 
DialogShutDown 58 
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DialogStartUp 45 
dialog windows 116,136 
dials 125 

digital oscillator chip (DOO 8, 175 
direct page 4, 202, 203, 283 
direct-page/stack segment 
202-207, 260, 262 
PraDOS 16 default 206 
direct- page/stack space 192, 203, 
260, 296 
location and arrangement 204 
for tool sets 42 
direct register 4, 203, 262, 293, 

294 
disabling 
dialog items 13S 
interrupts 293 
menus and menu items 1 16 
148 
disassembling 248 
disassembly, watching while running 

disk port 8 

disks 14, 298-301 

Disk II, slot for 9 

DispFontWindow 53 

display rectangle dialog items 137, 

139 
DisposeAll 193, 194 
DisposeHandle 57, 190 
disposing of memory handles 194 , 

277 
dithered colors 101-103 
dividing line (menus) l4s 
DoAboutltem 55, 142 
DOC (digital oscillator chip) 8, 175 
DochooseFont 97,121,305 
noChooserltem 56, 167 

DoCloselterci 56, 57 

document coordinates 83 
document window 110, 111, 133 
DoMenu 54, 153 
DoOpenltem 55, 120, 163, 305 
DoPrintltem 56, 170 
DoQuitltem 56 
dormant 200, 259 
DoSaveltam 56, 164, 213 
DoSetMono 56 
DoSetupItem 168 
DoSetUpItem 56 



DaTheOpen 121,211,305 

double-clicking (mouse) 71 

Double Hi-Res 7 

DoWindow 56 

down arrow (scroll bar part) 126 

draft printing 171 

drag area/dragging 71,110,114 

Drag Window 114, H 5 

DiawDialog 134 

drawing contents of windows 

115-116 
drawing mask 85 
DrawMenuBar 47, 154, 155 
DrawString 44,94, 106, 143 
DrawTopWIndow 170 
driverEvt 69 
drivers. See device drivers 
DumpOBJ utility (APW) 223 
dynamic segments 23, 25, 195, 
196, 200, 232 

programming examples 245 

unloading 246 



ED ASM assembler 296 
editable text 138 
Edit menu 32, 133 
Clear command 32 
Copy command 32, 141, 159, 

160 
Cut command 32, 141, 159, 160 
Paste command 32, Hi 159 

161 
Undo command 32, 277 
editor (APW) 222 
8-bit Apple II. See standard Apple 

I! 
80-column text display 6, 260 

slot for 8 
EMShutDown 58 
EMStaitUp 43 
emulation mode 4, 9, 173, 269, 

291, 293 
EndUpdate 115, 134 
EOF 214 

Equal utility (APW) 224 
erasing (QuickDraw N) 87, 91 
error handling (HodgePodge) 
306-310 



errors 
Apple HGS Toolbox 65, 66, 67 
printing 172 
testing for 277 

EVENT, ASM 330-336 

EVEST.ce 385-389 
event code 69, 73 
event-driven programming 
techniques 13-16, 51 
event handling 15-16, 67-75 

51-57 
event loop. See main event loop 
Event Manager 16, 20, 48, 63, 

67-75 
event mask 70, 74, 265 
EVENT, PAS 422-424 
event queue 68-70 
event records 67, 70 
events 48- See also specific event 
compared to interrupts 67 
controls and 129-130 
defined 14, 67 
types of 69-70, 74 
execution modes. See emulation 

mode; native mode 
Exerciser (ProDOS 16) 253-254 
expansion memory 6 
extended task event record 54, 74, 

153 
extended type 179 
external references 197 



fields within records 36 
file attributes 214 

access 215 

auxiliary type 217 

creation and Jasl-modification dale 
and time 215 
File menu 32, 133, 166 

Choose Printer command 32, 
166, 289 

Close command 32 

Open command 32 

Page Setup command 32 

Print command 32 

Quit command 32, 58 

Save As command 32 

Save command 50 
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filename 208 
files 215 

accessing 162-165 
closing 210 

controlling user access to 218 
creating 210 
destroying 210 
flushing 210 
Hodge Podge and 33, 34 
170 buffer 210 
opening 162, 210 
reading 211-214 
saving 164 
■writing 211-214 
Files utility (APW) 224 
file type 215-217, 256 
$04 218 
$06 218 
JB0 218 

SB3 256-259, 261, 297 
SB5 256, 261-262 
$B6 256, 266, 300 
$B7 256, 266, 300 
$B8 256, 265, 300 
SB9 256, 263, 300 
$BA 256, 300 
$C1 215, 218 
filling (QuickDraw ID 87, 91 
fill mode 100 
FindControl 129 
FindMaxWidth 105 
FindWindow 74, 114, 115, 129, 152 
Firmware xviii, 294 
FixAppleMenu 47, 158 
fixed address (memory -block 

attribute) 187 
fixed bank (memory-block 

attribute) 187 
fixed (memory-block attribute) 

187, 189, 195 
fixed type (Integer Math) 179 
FixMenuBar 47 
nag word (QUIT) 202 
FLUSH 210 
flushing files 210 
FMShutDown 58 
FMStartUp 46 
FONT. ASM 36I-366 
F0NT.CC 405-408 
font families 95 



font height 93 

Font Manager 21, 64, 92, 94-96 

font name 95 

font number 95 

font. pas 434-436 

fonts 21, 34, 92, 94-97 

where stored on disk 96 
font size 95 
Fonts menu 33 
font strike 94 
font style 96 
font subs itut ion 1 67 
font windows, Hodge Podge and 

34, 53, 104-106, 305 
foreground color 92 
foreground pixels 93 
frac type (Integer Math) 179 
frame 81 

aiert window 110 
colors 111 
controls 129, 130 
document window 110 
region 112 

scroll bars 117, 129, 288, 289 
window 109 
framing (QuickDraw II) 87, 91 
free-form synthesizer 176 
FrontWindow 57, 154, 165, 170 
full pathname 208 
function number (tool set) 66, 274 
FWEntry 294 



game I/O connectors 2, 8 
generators (sound) 176 
GET_EOF 214 
GetFamlnfo 97, 105 
GET.FILEJNFQ 214 
GetFontFlags 105 
GetFamlnfo 105, 123 
GET_LEVEL 211 
GET_MARK 214 
GetNewModa! Dialog 134, 142 
GetNextEveni 48, 68, 70, 73, 74, 
113, 114, 129, 152, 153, 286 
GctPen 106 
GetPon 52, 53. 97, 134 
GET_PBEF1X 209 
GelTick 181 



GetWRefCon 52, 53, 57, 154, i65, 

171 
global coordinates 70. 77, 82-84 
global page (ProDOS 8) 292, 296 

GLOBALS . ASM 373-376 
GLOBALS . PAS 152, 443-446 
global symbols 238 
GLU. See Sound GLU 
go-away box/area 110, 114 
GrafPon 81-82, 103, 108, 136 

printing 170 

relation to windows 108-109 
graphic ports 76, 81, 103 
graphics tablets 8 
grow box/area 48, 114 
GrowWindow 114 



H 

handles 189, 190 

hardware. See Apple HGS 

HeartBeal 181 

HeartBeai Interrupt Task queue 

181 

HidePleaseWait 46, 134 

HideWmdow 114 

hierarchical file system 288 

high-level languages 65 282-283, 
290 

highlighting 72. 116, 128, 153 

high-order byte, of handles 190 

HiliteMenu 54 

Hi-Res 7 

Hi-Fes video display 7 

Hi Word 54 

HLock 104, 211 

HodgePodge 30-60- See also 
specific subroutine 
"About," dialog box 142-144 
assembly language 65-66, 190, 

202, 311-376 
auxiliary type 218 
C 377-412 

code-listing conventions xxii, 36 
control manipulation 130 
desk accessory suppon 158 
differences between the 
languages 69, 74, 105 
direct-page/stack space 206 
Edit menu disabled l6l 
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error handling 306-310 

event handling 51-57 

Hies 33, 34 

font windows 34, 53, 104-106, 
305 

general description XX 

languages 35 

Macintosh resource equivalents 
285 

main event loop 48-50 

main program 36, 37 

memory- block attributes 188 

menus 31-33. 47, 153 

mouse events and 71 

organization of 35-36 

Pascal 36, 413-446 

picture files 215-217, 218 

picture windows 33, 52-53, 
103-104, 305-306 

QuickDraw II coordinates and 82 

QUIT 202 

scrolling and 117 

shutting down 57, 58-59 

starting up 38-47, 64 

subroutines 35, 59-60, 302-304 

System Loader and 195 

Taskmaster and 51-53, 75, 286 

update routine 116 

User ID use 193 

versions of 35 

windows 56-57,72,120-124 
horizontal blanking 100 
HP, ash 312-314 
HP.CC 37B-381 
HP.H 411^112 
HP. PAS 414-418 
Human Interface Guidelines 

xix-xx, 11-13, 139, 146, 277 
HUnLock 104, 211 
hybrid applications 292-293 

I 

icons 10, 285, 286 
ID. See item ID; menu ID; User ID 
image pointer 80 
image width 80 
I mage Writer 167 
inactive controls 128 
as dialog items 138 



inactive windows 115 
index registers 4, 294 
information bar 110 
init.asm 315-323 
InitCursor 124, 165, 170, 309 
JnitGlobals 35, 39-^1, 150 
initialization files 256, 266 
initialization segment 196 
initializing data structures 

(Hodgepodge) 38-41 
initializing. See starting up 
Initial Load 260 
in it routine (NDA) 264 
In it utility (APW) 224 
InsertMenu 47 
InsertMltem 154, 155 
InstallFont 105, 123 
instrument 177 
lnt2Hex 307, 309 
Integer Math strings 179 
Integer Math Tool Set 22, 179 
integer type (Integer Math) 179 
interactive programming 13, 14 
international markets 277 
interrupt control routines 181 
interrupt environment 269 
interrupt handlers 182, 183, 256, 

267-272 
interrupt mode (Note Sequencer) 

178 
interrupts 176, 177, 178, 267 
compared to events 67 
disabling 293 
IntToString 105, 122, 165 
InvalRgn 117, 118 
inverting (QuickDraw II) 87, 91 
invisible controls 128 
invisible dialog items 138 
I/O. See also slots 
buffer files 210 
built-in 2, 8-9 
serial ports 8 
IOASM 371-372 
item character (menu and item 

lines) 150 
itemDisable 138 
item ID 
dialogs 137, 139 
menus 54, 151-152, 155 
items 



dialog 137-140 

menus 149 

Note Sequencer 178 



Job dialog box 169 

joysticks 8 

JSL 294 

JSR 294 

Jump Table 196, 198 



keyboard 2, 8, 10 
keyboard equivalents 148, 153 
key-down events 15, 16, 69, 
71-72, 73 

keyDownEvt 69 
KIND 205 



language considerations (APW) 225 

LaserWriter 167 

launching Under ProDOS 16 

200-202 
leading 93 
LEShutDown 58 
LEStartUp 45 
LETextBox 142 
LETextBox2 142 
library dictionary segment 238 
library files 238-239 
licensing Apple software 279 
LineEdit scrap 141, l6l 
LineEdit Tool Set 21, 64, 138, 139, 

141-142 
line (QuickDraw II) 87, 88-89 
Link Ed 205, 234 
assigning load segments with 

236 
linker (APW) 222, 223, 235-238 
Lisa 14 

list controls 131 
List Manager 20, 64, 131 
lists 130-131 
ListShutDown 58 
ListStanUp 46 
Loader Dumper 247, 249, 250 
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load files 23, 26, 196, 226-229 

order of load segments in 235 
loading 

applications (System Loader) 

198, 199 
relocatable segments (System 

Loader) 197 
segments 198 
tool sets 63 
LoadOne 164, 211, 306 
load segments 194-195, 196, 230, 
231-234 
assigning with LinkEd file 236 
assigning in source code 

234-236 
characteristics of 232 
difference from object segments 

230 
dynamic 232 
memory blocks and 194 
number of 232 
order in load file 235 
types of (System Loader) 196 
LoadTools 42, 44, 63 
local coordinates 77, 82-84, 103, 

105, 117-118 
local references 197 
location information 76, 79 
Loclnfo record 76, 79, 81, 103 
locked handles 187, 189. 195, 277 
longint type (Integer Math) 179 
LoWord 43, 54, 121, 123 

M 

MacGen utility (APW) 224 
Macintosh 13, 14, 17, 167, 180 

Control Manager 288 

converting programs to the Apple 
I1GS 282-289 

desk accessories 156, 289 

file system 287-288 

Memory Manager 288 

Print Manager 289 

QuickDraw 286-287 

resources 285 

Standard File Package 289 

TaskMaster not available 286 

toolbox compared to Apple 1IGS 
284-289 



Window Manager 288 
macros 222 65 
MainEvent 35, 36, 50 
main event loop 14-15, 16, 48, 67 

HodgePodge and 48-50 
mainID 192 
main program (HodgePodge) 36, 

37 
main routine 233 
MakeATemplate 140,310 
MakeLib utility (APW) 224, 238 
manager. See tool sets or specific 

tool set 
HanyWindDialog 120 
Mark 214 

master color values 98 
master User ID 192, 193 

DisposeAll and 194 
math tool sets 22, 178-180 
maximum segment size 23 
memory 2, 4, 5-6, 76 

allocatable by Memory Manager 

191 

allocation 191-194 

compaction 188 

disposal 193 

minimum configuration 5 

RAM expansion 5 

requirements (Apple NGS 
Toolbox) 5 

ROM expansion 5 

special 187 
memory banks 6 

SCO 4, 6, 192, 203. 248, 267, 
270, 293-296 

$01 6, 295 

JEO 6, 295 

JE1 6, 267, 295 
memory blocks 187, 197, 247 

attributes 187, 188 

disposing of 194, 277 

handles to 189 

Load segments and 194 

pointers to 189 

purgeable 194, 233 

unlocking 194 
memory fragmentation 188 
memory image 228 
Memory Manager 20, 22, 23, 42, 
63, 180, 186-195, 288 



Memory Mangier 247 

memory protection ranges, using 

252 
menu. ASH 324-329 
menu bar 115, 146, 147, 152 
MENU.cc 382-384 
menu-event handling 

(HodgePodge) 54-56 
menu ID 54, 55. 151-152, 155 
menu Interface 13 
menu items 146 
disabled 148 

keyboard equivalent 149, 153 
menu lines 149, 265 
Menu Manager 21,47,64,71, 

146-155, 264 
MENU. PAS 419-421 
menus 10, 14, 21, 116, 146. See 
also specific menu/menu 
command 
accepting user input 152-153 
appearance 148-149 
constructing 149-152 
custom 149 
disabling 116 
dividing lines 148 
HodgePodge and 31-33, 47 
modification of 154-155 
organization of 149 
MenuSelect 115 
menu selections, handling 153 
MenuShutDown 58 
MenuStartUp 45 
menu title 146, 153 
message dialog box 135 
message (event-record field) 70 
MIDI (Musical Instrument Digital 

Interface) 178 
mini-palettes 7, 99 
Miscellaneous Tool Set 20, 22, 42, 

181-182, 248 
missing characters/symbol 95 
MMStartUp 43 
ModalDialog 141, 144 
modal dialog boxes 133, 139 
modeless dialog boxes 133, 136 
modes (program) 12, 133 
modifier key 71 

modifiers (event-record field) 70, 
71 
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Mon itor program 267 

debugging with 247-248 
MountBootDisk 45,307-308 
mouse 8, 10 
dicks 14, 15, 48 
double-dicks 71 
slot for 9 
mouse-down events 15, 16, 69, 71, 

73, 129 
mouseDownEvt 69 
mouse routines (Miscellaneous Too] 

Set) 182 
mouse-up events 69, 71 
mouseUpEvt 69 
movable (memory-block attribute) 

188 
MoveTo 43, 94, 106, 143 
MTShutDown 58 
MTStanUp 43 
multiple-language programs, 

debugging 252-253 
multiple-segment programming 

examples 24 1-245 
Munger routine (Miscellaneous Tool 

Set) 162 
Musical Instrument Digital Interface 

CMIDI) 17S 

N 

native mode 4, 173, 271-272, 274, 

291 
NDA- See new desk accessory 
new desk accessory (NDA) 156, 
263, 289, 300. See also classic 
desk accessory; desk 
accessories 
programming examples 265 
supporting 157-158, 161 
writing 264-265 
NewDIlem 134, 143 
Newllandle 41, 43, 122, 192, 211 
NEWLINE 211 
NewMenu 47, 149 
NewModal Dialog 142, 143 
NewWindow 109, 124 
New Window parameter list 109, 

121, 123 
NIL 190 
Note Alert 135 



Note Sequencer 22, 177-178 
Note Synthesizer 22, 177. See also 

sound/sound hardware 
notXOR mode 87 
null event 69, 73 
nullEvt 69 
null prefix 209 
numeric keypad 8 



object files 26, 226-229 
object module format xviil, 26, 

198, 226, 257, 296 
object segments 230-231 
offset (into color table) 99 
OK button 132, 133, 139 
OMF. See object module format 
OPEN 210, 211, 213 
Open command (File menu) 32 
OpenFilter 162, 164, 218, 306 
opening Hies 162, 210 
OpenNDA 158 
OpenPort 97 
open routine (NDA) 265 
OpenWlndow 55, 120, 121, 163, 

305 
operating-environment tool sets 

22, 180-183 
operating systems xix 

calls (typographic convention for) 
xxii 
origin 
of character 93 
of QuickDraw u coordinate plane 

77 
of rectangle 82 
oscillators (sound) 175-176 
ovals (QuickDraw II) 87, 90 
overlays 233 



PackBytes routine (Miscellaneous 

Tool Set) 182 
page-aligned (memory-block 

attribute) 187 
page-down region (scroll bar part) 

126 
page settings, printing 167-168 



Page Setup command (File menu) 

32 
page-up region (scroll bar part) 126 
Paint 52-53 

painting (QuickDraw II) 87, 91 
Paint It 52-53, 104, 170 
PAINT. PAS 439-442 
palettes 7, 99-100, See also color 
palette; color tables 
standard (640 mode) 102 
standard (320 mode) 100 
parameter lists (ProDOS 16) 214 
parameter-passing 253 225 
ParamText 141 
part code 127 
partial pathname 208 
parts, standard window HO 
Pascal 65, 202, 225 

Hodgepodge and 36, 413-446 
Pascal siring 92 
Paste command (Edit menu) 32, 

141, 159, 161 
patching 24, 227 
pathnames 196, 208, 288 

pointer (QLJTT) 202 
Pathname segment 196 
pathname table 196 
pattern 

Note Sequencer 178 
QuickDraw II 85 
pen 85 

pen location 84, 85, 92 
pen mode 86, 173 
pen pattern 85 
pen size 85 
permanent initialization files 266, 

300 
phrase (Note Sequencer) 178 
picture files, HodgePodge and 

215-217, 218 
picture (QuickDraw II) 92 
picture windows, HodgePodge and 
33, 52-53, 103-104, 305-306 
pixel images 76, 103-104, 112, 
171, 286 
defined 79 
pixels 77, 79 
background 93 
defined 7 
foreground 93 
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relation to coordinate plane 

locations 78 
shape of 77, 90, 284 
plain-styled characters 95 
plane (window) 113, 136 
PMShutDown 58 
PMStartUp 46 
pointers 189-190 
pointing devices 10, 71 
point (QuickDraw II) 88-89 
point (typesetting) 95 
polygon (QuickDraw ID 87, 96 
port (printer) l66 
port (QuickDraw ID See graphic 

ports; GrafPort 
port rectangle 81-82, 83, 103. 108 

120 
portSCB 80 
pos ition-independent 

code/segments 188, 195, 196, 
197 
PPToPort 103, 104, 118 
PrChooser 167 
PrCloseDoc 170, 172 
PrClosePage 170, 172 
PrDefault 41 
prefixes 208-210, 288 

Initial values 210 
prefix numbers 208-209 
PRINT. ASH 367-370 
print. cc 409-410 
Prim command (File menu) 32 

printing 166-173 

background procedure 173 

choosing a primer 1 66-1 67 

draft 171 

errors 172 

GrafPort 170 

page settings, making 167-1 68 

printing loop 172 

QuickDraw 11 and 170, 172, 173 

spool 172 
printing loop 172 
Print Manager 21, 64, 76, 166-173 

289 
PRINT. PAS 437-438 
print records 171 
private scrap l6l 
PrJobDialog 170 
ProDOS 8 xix, 9, 207, 257, 290 






global page 292, 296 
ProDOS 16 compared to 291, 

296 
ProDOS 16 QUIT call and 202 
ProDOS file system xix, 207-218 
ProDOS 16 Xix, 10, 199, 200-202, 
257-259, 260 
compared to Macintosh Tile 

system 287-288 
compared to ProDOS 8 291, 296 
direct-page/stack segment, 

default 206 
Exerciser 253-254 
interrupt handling 271-272 
parameter lists 214 
prefixes 208-210 
QUIT call 58, 202 
shell applications and 262 
Program Bank register 293 
pf ogram descriptions (AFW) 

221-224 
program launcher 201 
programming examples. See oho 
Hodge Podge or specific 
routine 
assembly language 190, 193, 

239-246, 263, 265, 311-376 
C 190, 377-412 
classic desk accessory 263 
dynamic-segment 245 
multiple -segment 241-245 
new desk accessory 265 
single-segme nt 24 0-24 1 
programming techniques 

absolute vs. relocatable segments 

24, 227 
applications 26, 228-229, 

256-259 
assembly- language 4, 283-284, 

290 
auxlD field 193 
controlling programs 259-260 
control-related events 129 
cutting and pasting l60-l6l 
desk accessories 262-265 
desktop 10 
dialogs and alerts 141 
Edit menu l6l 
error testing 277 
event-driven 13-16, 51 



event handling 70 
file types 255-274 
general xvii, 11, 277 
high-level languages 282-283, 

290 
HodgePodge, using 34-36, 276 
hybrid applications 292-293 
initlalizauon files 266 
interactive 13, 14 
interrupt handlers 270, 271-272 
language considerations 225 
loading programs 199 
loading segments 198 
load-segment characteristics 232 
Macintosh program conversions 

282-289 
math computing 178-180 
memory allocation 191-194 
menu modification 154—155 
menu organization 149 
object module format and 26 
parameter-passing 225 
Print Manager 171-173 
restartability and C 259 
segmentation 23-25, 219-254 
shell applications 261-262 
standard Apple II program 
enhancement 290-297 
static vs. dynamic segments 25, 

232-235 
System Loader 195 
TaskMaster and 75 
tool sets 18, 62, 272-274 
window drawing 103-106, 

115-116 
window origin, resetting 120 
window-related events 113-120 
program selector 201 
PrOpenDoc 170, 172 
PrOpenPage 170, 172 
PrPicFile 170, 172 
PrStl Dialog 169 
ptrToPixImage 80 
pull -down menus. See menus 
purgeable memory blocks 194, 

233 
purge level 387, 195 
purging 190, 194, 195, 197, 200 
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Q 

QDAuxShutDown 58 
QDAuxStariUp 45 
QDShuiDown 58 
QDStanUp 43 
QuickDraw (Macintosh) 136 
286-287 
relation to QuickDraw [I 75, 77, 
79. 286-287 
QuickDraw II 20, 42, 63, 75-106, 
170. See also specific topic 
blade and while drawing 103 
color 98-103 
coordinates 77, 82 
how ii draws 85-88 
limits to drawing 77 
Macintosh QuickDraw, relation to 

75, 77, 79, 286-287 
pattern 85 

printing and 170, 172, 173 
text drawing 92—97 
what it draws 88-92 
where it draws 76-84 
QuickDraw II Auxiliary 20, 75 
QUIT 58, 199, 200-202, 260, 
261-262 
flag word 202 
in high-level languages 201 
pathname pointer 202 
Quit command (File menu) 32, 58 
quit return stack 201 



radio buttons 125, 128 

RAM 6, 9, 18- See also memory 

RAM-based tool sets 43, 63 

RAM expansion 5 

RAM patches (tool sets) 43, 293 

READ 211 

reading files 211-214 

rectangles (QuickDraw ID 87, 89 

data structure 90 

origin of 82 
reentrant code 182 
RefreshDesktop 45 
regions (QuickDraw ID 87, 91 

defined 112 
registers 4, 66, 283 



RELOAD segments 200, 207, 259 
relocatable code 23, 24, 196, 197, 

226-227, 291 d 295 
relocation dictionary 228 
required tool sets 62-63 
resources (Macintosh) 285 
Restart 200 

restartabiliiy, C and 259 
restarts Die 197, 200, 259 
rcstan-frorn-memory flag (QUIT) 

202 
restarting programs in memory 

199-200 
return flag (QUIT) 202 
RGB video 2, 7 
right scroll bar 110, 111 
ROM 9, 18. See also memory 
ROM expansion 5 
rounded-corner rectangle 

(QuickDraw II) 87, 90 
routines (HodgePodge) 35, 59-60, 
303—304. See also specific 
routine 
routines (tool set) 17. See also 
specific routine 
how to call 65-67 
routine numbers 66 T 274 
total number of 62 
RTI 269 
RTL 260, 261, 262, 265 



sample programs, See also 

Hodgepodge; programming 

examples 
SANE (Standard Apple Numeric 

Environment) xix-xx 
Save As command (File menu) 32 
Save command (File menu) 50 
SaveOne 164, 165, 213 
saving files 164 
scaled fonts 287 

defined 96 
scan-line control byte 80, 100 
Scheduler 22, 1S2-183 
Scrap Manager 21, 64, 158, 

159-161, 264 
ScrapShulDown 58 
ScrapStartUp 46 



screen memory 76, 79 

scroll bars 72, 110, 112, 117, 126, 

129 288, 289 
scrolling 73, 112, 117-120 
ScrollRect 117, 118 
Search utility (AFW) 224 
segmentation 23-25, 228, 
230-238, 284 219-254 
absolute 24 
direct-page/stack 204 
dynamic 25, 195 
maximum segment size 23 
object 230-231 
relocatable 24 
static 25, 195 
segmented programs, debugging 

249 
SelectWindow 114 
self-booting applications 257-258 

257-258 
sequence (Note Sequencer) 177 
serial ports 2, 6, 9. See also I/O 
SetBackCoIor 43, 94, 143 
SelCtlParams 127 
SetDAFont 14 1 
SET_EOF 214 
SET.FILEJNFO 214 
SetFonlFlags 105 
SetForeColor 43, 94, 143 
SET_LEVEL 211 
SET_MARK 214 
SelMenuFtag 154, 155 
SetMItem 165 
SetMltemID 155 
SetMTiUeStart 47 
SetOriginMask 124 
SetPenMode 17 
SetPenSize 17 
SetPort 97, 124, 134, 143 
SET_PREFIX 209 
SetRect 39, 40, 41, 104, 122, 123, 

134 
SetTextFaee 143 
SetOpDefault 35,41, l68 
SetUpMenus 35,36,47,158 
SetOpwindows 35,41,123 
SetWTitle 165 
SFAllCaps 45 
SFGetPile 162, 163 
SFPutFile 164, 165 
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SpShutDown 58 

SFStartUp 45 

shadowed rectangle 148 

shape of pixels 77, 90, 284 

Shaston 95 

shell 197 

shell applications 24 1, 256, 259, 

261-262 
Shell (APW) 199, 221-222, 259, 

261 
shell identifier 261 
Show Cursor 44 
ShowFom 53, 97, 105, 170 
showPleaseWait 46,116,134, 

142 
shutDownTools 35,58,158 
shutting down 197, 199-200 

HodgePodge 57, 58-59 
single-segment, programming 

examples 240-241 
640 mode 7, 80, 98, 99 102 
65816 microprocessor Jtiv, 3-5, 10. 

65, 291 
6502 microprocessor xxi, 3, 9, 

294-295 
size box 110, 111, U2, 114 
size of coordinate plane 77 
Si2eMCindow 114 

slots 2, 6, 8-9, 166. See also I/O 
for 80-column text display 8 
for mouse 9 
SmartPort, slot for 9 
smoothing l67 
Software Licensing 279 
SOS 215-217 
Sound GLU 8, 175 
sound/sound hardware 2, 8, 9, 22, 
135. 174-176. See also Note 
Synthesizer 
Sound Tool Set 22, 176 
source files 26, 226-229 
assigning load segments in 
234-236 
specialized tool sets 22 
special memory 187 
spool printing 172 
stack 4, 203, 269, 284, 293, 296 
slack overflow 207 
stack pointer 203. 262, 269, 294 
Stack underflow 207 



Standard Apple Numeric 

Environment (SANE) xix-xx 
Standard Apple Numeric 

Environment Tool Set 22, 
179-180 
standard Apple II 4, 10, 203, 290 
compatibility of Apple HGS with 

9-10, 291-292 
denned xxi 

program enhancement 290-297 
Standard File Operations Tool Set 

21, 64, 162-165. 288, 289 
standard linker (APW) 223, 235, 

238 
standard window parts 110 
START 257, 258 
starting up 

HodgePodge 38-47, 64 
tool sets 38-41, 42-46, 62-67 
startUpTools 35, 36, 42, 158, 

188 
static segments 25, 195, 196, 200, 

232-235 
static text 140, 141 
step mode (Note Sequencer) 178 
StopAlert 309 
Stop Alert 135 
structure region 112 
Style dialog box 167 
styled variations (fonts) 34, 95, 96 
subroutines 230 
Hodgepodge 35, 59-60, 
303-304 
Super Hi -Res xviii, 2, 6-7, 98, 284 
available colors 7, 98 
color palettes 7 
640 mode 7, 99, 102 
320 mode 7, 99, 101 
switch events 68, 69, 73 
switchEvt 69 
sw itch ing execution 1 99 
symbolic reference 226, 238 
synthesizer. See Note Synthesizer; 

sound/sound hardware 
SysBeep routine (Miscellaneous 

Tool Set) 182 
SysFailMgr 307 
SystemClick 158 
system clock 9 
system disk 298-301 



application 300—301 
complete 298-300 
SystemEdit 158 
system event mask 70 
System Failure Manager 176, 181 
system file levels 201, 211 
system library prefix 209 
System Loader 22, 23, 180, 
195-200, 259 
loading applications 198 
loading relocatable segments 

197 
types of load segments 196 
system menu bar 147 
system program (ProDOS 8) 257 
SYSTEM. SETUP/ subdirectory 300 
system windows 111 



lask codes 48, 70, 74 

task Data field 54, 153 

task mask 74 

TaskMaster 48, 50, 51-53, 73-75, 
113-117, 152 
compared to GelNextEvenl 68 
in converting Macintosh programs 

286 
desk accessories and 158 
extended task event record 74 
frame controls and 129, 130 
Hodgepodge and 51-53, 75, 

286 
menu -select ion handling 153 
programming techniques and 75 
scroll bars and 117 
window-related events and 115 

templates 140, 285 

temporary initialization files 266, 

300 
termination character (menu and 

item lines) 150 
text 92-97, 104-106 
text block 92 
text document 112 
text mode 92 
text strings 285 
Text Tool Set 21, 173, 26l 
320 mode 7, 80, 98, 99, 147 100 
thumb (scroll bar part) 126, 129 
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title bar 110, 111, 114 

title character (menu and item lines) 

150 
TLMcuntVoJume 307, 308 
TLStartUp 43 

toolbox-defined constants 38, 50 
toolbox-defined data structures 38 
Toolbox. See Apple IIGS Toolbox 
tool initialization 134 
Tool Locator 18, 20, 42, 62, 65-66, 

272-273 
tool numbers 273 
tool sets 17-22, 291, See also 

Apple IIGS Toolbox or specific 
tool set 
advantages of using 18 
basic 20 

categories of 19-22 
denned 17 

desktop-interface 20-21 
device- interface 21 
direct-page space for 42 
function numbers 66, 274 
independence from operating 

system 18 
loading 63 
math 22 
number of 62 
numbers 66, 273 
operating-environment 22 
programming techniques 16, 62, 

272-274 
RAM-based 43, 63 
RAM patches 43, 293 
required 62-63 
sound 22 
specialized 22 
starting up 38-41, 42-46, 62-67 

62-67 
user- written 272-274 
version number 63 
where stored on disk 63 
TOOL. setup 300 
tool table 42, 63 
Track Control 71, 129 
TrackGoAway 114, 115 
tracking 153 
Track Zoom 114 
translation 277 
trigger value 251 



typelD 192 
types 36 

U 

underlining 96 

Undo command {Edit menu) 32, 

277 
unhighlighting 72, 153 
unloading 197, 198, 233, 246 
unlocking handles 194, 277 
unpurgeable 195 
up arrow (scroll bar part) 126 
Update events 68, 69, 72, 115, 118 
updateEvt 69 
Update region 115, 117 
update routine, HodgePodge and 

116 
updating 72, 73 
user-defined constants 36 
User ID 192-194, 201, 202, 241, 

247, 261 
User ID Manager 182, 192 
user interrupt vector 268, 270 
User Shutdown 199, 200, 260 
user tool sets 256, 272-274 
user- written tool sets 272-274 
utilities CAPW) 223 



value controls 125, 128, 130 
variable initialization (HodgePodge) 

38-41 
vector routines 181 
versions 301 

of HodgePodge 35 

of tool sets 63 
video display 2, 6-7. See also 
Super Hi-Res 

Double Hi-Res 7 

80-column text 6, 8, 260 

Hi-Res 7 
visible region 81, 82, 84, 115 
visRgn 82 
volume name 208 



W 

WaitCursor 46, 165, 170, 211 



wContDefProc 109 

wedges 91 

wframe 109 

what (event-record field) 70 

when (event-record field) 70 

where (event-record field) 70 

width (field in Loclnfo record) 80 

HlnactMenu 75 

wrncanterit 74 

win Desk 7-4 

winDeskitem 75 

WINDOW. ASM 337-352 

WiNDOw.cc 390-399 

window content definition 

procedures 51 
window drawing, programming 

techniques 103-106, 115-1 16 
window events 51, 72 

HodgePodge and 56-57, 72 
window frame 109,111 
window list 154 
Window Manager 20, 64, 71-73, 82, 

91, 108-124 288 
window menu bars 147 
window origin, resetting 1 20 
window. pas 425-428 
window records 109 
window- related events 
programming techniques 

113-120 
TaskMaster and 115 
windows 10, 14, 51, Si, 82, 
108-124 
active 114, 115, 116 
alert 110, 111, 116, 136 
application 111 
basic features 108-113 
Controls and 129 
custom 111 
default properties 108 
definition procedures 51 
dialog 116, 136 
document 110, 111 
draw ing contents of 115-116 
frame colors 111 
GrafPorts, relation to 108-109 
HodgePodge and 57, 120-124 
inactive 115 

port rectangle origin 120 
scrolling 117-120 
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Index 



standard parts 110 
system 111 
Windows menu 32 

wlndrag 74 

WindShulDown 58 

WLndStartUp 45 

wmdStatus 58 

wlnFrame 75 

wlnGoAway 74 

wlnGrow 74 

wlrslnfo 75 

wlnWenuBar 50,54,74,153 

wlnSpecial 75 

wlnSysWindow 75 

wlnZoom 74 

wBefCo^ 109 

WR]TE 211, 213 

writing to Tiles 211-214 



X 

X register 66, 26 1 

¥ 

Y register 26l 

Z 

zero page 203, 269, 293, 296 
zoom box/area 48, 110. Ill, 112, 

114 
ZoomWindow 114 
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Programmer's Introduction to die Apple IIgs* 

The Official Publication from Apple Computer, Inc. 

Tlic Apple II* .s" personal computer— with its high speed, expandable memory 
super-high-resotution color graphics, and extensive Toolbox of programming 
routines— his created a powerful new programming environment Written for 
programmers and software developers, Programmer's introduction to tix Apple fifes 
explains essential concepts and provides tips and practical advice from die designers 
oftiie Apple Dgs Tbotbos and the new ProDOS* 16 operating system. 

To illustrate these concepts, Programmer's bmoduaitin to fbeAppleHGS includes 
three complete versions of a functioning sample program called HodgePodge— m 
65816 assembly language, C, and Pascal. Using 1 1* >dgcPodge as an example, the hook 
demonstrates: 

■ Event-driven pmgramming techniques 

■ Programming widi die Apple* Desktop user interface 

■ Effective use of the Apple Hgs Toolbox 

■ How to write segmented, relocatable code that will make programs run more efficiently 
- File handling 

• Memory management 

• How to write specialized pmgrams such as shells and desk accessories 

Appendices include complete source code listings of HodgePodge in all three 
languages, as well as hints on converting Apple Macintosh* programs and earlier Apple 

II programs for die Apple llus. 

Programmer's Introduction to the Apple lies contains a 35-inch disk that includes both 
source code and executable versions of HodgePodge. 
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